VIGO has four entry points. Most projects use two of them together: the compiler builds a City once from raw data, and the engine answers queries from that City for as long as you like.

Download archives from VIGO releases. Each archive targets one operating system and CPU; City data moves freely between the supported 64-bit targets.

Engine

Extract the engine archive and check the executable:

./vigo --version
./vigo capabilities --pretty

.\vigo.exe --version
.\vigo.exe capabilities --pretty

The executable contains the routing kernels, the City loader, the JSON interface, the HTTP server, and SQLite. It needs no compiler, Node, Python, browser, or internet connection to answer a query. The archive also contains this guide, the OpenAPI document, the engine manual, an audit record, licenses, and a manifest.json that hashes every file.

Compiler

The compiler archive contains vigo.mjs, its matching native routing kernel, license notices, and a checksum manifest. Keep vigo.mjs and vigo-routing-kernel.node in the same directory, then check it with Node.js 24.18 or newer:

node vigo.mjs --version
node vigo.mjs capabilities

The compiler builds Cities and scenario collections, and runs Route, Matrix, Reach, Stream, and Compare against them. It does not bundle Node or City data. The same steps ship inside the archive as its README.

Build from source

Use Node.js 24.18 or newer, npm 11.6 or newer, the Rust toolchain pinned in rust-toolchain.toml, and a C toolchain for the bundled SQLite. Build natively on the operating system and CPU that will run VIGO:

git clone https://github.com/hytangs/vigo.git
cd vigo
npm ci
npm run build:cli-runtime
npm run build:standalone

build:cli-runtime produces the compiler, public/vigo.mjs, and its native kernel. build:standalone produces the engine at native/vigo-routing-kernel/target/release/vigo. npm run build additionally compiles Studio, and npm run studio opens it.

Name the commands

The guides call the engine vigo and the compiler vigo-build. In a POSIX shell:

alias vigo="/absolute/path/to/vigo"
alias vigo-build='node "/absolute/path/to/vigo.mjs"'

From a source checkout, point them at native/vigo-routing-kernel/target/release/vigo and public/vigo.mjs. On Windows, use .\vigo.exe and node .\vigo.mjs, or define your own functions. Both commands accept --name value and --name=value and reject unknown options.

Studio and Python

VIGO Studio is the desktop workspace. It imports GTFS and OSM into its own project library and opens this guide offline under Settings → Documentation. See the Studio guide.

VIGO Python is versioned separately. Install the wheel for your platform, then follow your first Python query.

Supported platforms

• macOS 13.5 or newer on Apple Silicon, Linux with glibc on ARM64 and x64, and Windows x64. Linux release builds use Ubuntu 24.04. There are no 32-bit or native Windows ARM64 binaries.
• The engine container image runs on Debian with glibc. See Deploy the routing engine.
• Studio maps require WebGL 2. The engine, the compiler, and Python need no graphics device.

In about ten minutes you will build a City for Boston and Cambridge from public data, then plan a journey from Harvard Square to South Station, compute a small matrix, and map where you can reach in 45 minutes. A City is the prepared data directory, here ./boston.

You need the engine and the compiler, named vigo and vigo-build, plus curl, unzip, and Osmium Tool. The commands use a POSIX shell; on Windows, use WSL for the download and extract steps.

1. Download the Boston inputs

Two files supply different parts of a journey:

No API key is needed. Choose the static GTFS ZIP, not GTFS-realtime, and the .osm.pbf, not a shapefile or GeoPackage.

mkdir -p boston-tutorial/data
cd boston-tutorial
curl --fail --location --retry 3 --output data/MBTA_GTFS.zip \
  https://cdn.mbta.com/MBTA_GTFS.zip
curl --fail --location --retry 3 --output data/massachusetts-latest.osm.pbf \
  https://download.geofabrik.de/north-america/us/massachusetts-latest.osm.pbf
unzip -p data/MBTA_GTFS.zip feed_info.txt
unzip -p data/MBTA_GTFS.zip calendar.txt

feed_start_date and feed_end_date give the published interval. The feed checked for this tutorial covers 2026-09-25 through 2026-12-12, and the examples use Monday 2026-10-05. With a later download, choose a date inside its interval and check calendar.txt and calendar_dates.txt: a date inside the interval does not mean every route runs that day. Times are local MBTA service times in America/New_York.

2. Build the City

Cut a smaller street extract around central Boston and Cambridge, then build:

osmium extract --bbox=-71.20,42.25,-70.95,42.45 --strategy=complete_ways \
  data/massachusetts-latest.osm.pbf --output=data/boston.osm.pbf
vigo-build build --gtfs ./data/MBTA_GTFS.zip --osm ./data/boston.osm.pbf \
  --output ./boston --prepare-date 2026-10-05
vigo info --city ./boston --pretty

The complete-ways strategy keeps every node of the ways crossing the rectangle. This extract covers the tutorial's places, not street access for the whole MBTA network; for a wider study, enlarge it or pass the full Massachusetts PBF. --prepare-date precompiles that day's timetable so that a fresh engine process can reuse it. Keep the providers' notices when you share data; see OpenStreetMap attribution.

VIGO writes one complete ./boston directory and leaves an existing output alone unless you pass --replace. vigo info confirms the City's name, revision, sources, and warnings. Keep the whole directory: the inspection output identifies the City but contains no routing data.

3. Plan a journey

Save route.json. Coordinates are [longitude, latitude]:

{
  "origin": {"coordinate": [-71.11902, 42.37334]},
  "destination": {"coordinate": [-71.05524, 42.35227]},
  "serviceDate": "2026-10-05",
  "time": "08:00",
  "maxWalkKm": 1.2,
  "maxTransfers": 3,
  "requireTransitRide": true
}

vigo route --city ./boston --request route.json
vigo route --city ./boston --request route.json --output route-result.json

In a terminal, the first command prints a short itinerary. The second saves the full JSON Result. To ask when to leave to arrive by 09:00, override the clock and time direction:

vigo route --city ./boston --request route.json --time 09:00 --arrive-by

vigo-build route --city ./boston --request route.json --time 09:00 --time-preference arrive

Command-line flags override fields in the request file. In JSON, the same choice is "time": "09:00", "timePreference": "arrive_by", which both runtimes accept.

4. Read the Result

Read status first. ok contains a journey; not_found is a valid answer meaning no journey satisfies the date, walking limit, transfer cap, and time horizon you asked for. Then read journey.departureTime, journey.arrivalTime, and the ordered journey.legs. Clocks are local service-day HH:MM:SS; durations are integer seconds.

Trip IDs and times depend on the feed you downloaded, and this is scheduled routing without live delays. Check warnings and each walk's quality before treating a path as a passenger-facing guarantee; walking evidence explains station costs and schematic links. Open route-result.json in the Result viewer to see the journey as a timeline.

5. Compute a matrix

Save matrix.json. The rows are Harvard Square and Kendall Square; the columns are South Station and Copley Square:

{
  "origins": [
    {"id": "harvard", "coordinate": [-71.11902, 42.37334]},
    {"id": "kendall", "coordinate": [-71.08618, 42.36249]}
  ],
  "destinations": [
    {"id": "south-station", "coordinate": [-71.05524, 42.35227]},
    {"id": "copley", "coordinate": [-71.07758, 42.34997]}
  ],
  "serviceDate": "2026-10-05",
  "time": "08:00",
  "maxWalkKm": 1.2,
  "maxTransfers": 3,
  "includeJourneys": true
}

vigo matrix --city ./boston --request matrix.json --output matrix-result.json

Read durationsSeconds[origin][destination] in request order, and the matching journeys entry when requested. An unreachable pair is null, never zero. Repeated origins or destinations share work internally, and every requested cell is still returned.

6. Map where you can go

Save reach.json to find the streets and areas reachable from Harvard Square within 15, 30, and 45 minutes:

{
  "origin": {"coordinate": [-71.11902, 42.37334]},
  "serviceDate": "2026-10-05",
  "time": "08:00",
  "cutoffsMinutes": [15, 30, 45],
  "extentRadiusKm": 6,
  "rasterSize": 48
}

vigo reach --city ./boston --request reach.json --output reach-result.json

surface.valuesSeconds is a row-major raster from the northwest corner, and areas holds GeoJSON polygons for each cutoff. A Reach surface describes modeled travel time; it is not a count of jobs or people. See Reach for resolution, sampling, and comparison rules.

7. Keep the City loaded

One-off commands open the City every time. For repeated work, keep one process resident. Save queries.ndjson with one request per line:

{"id":"harvard-south-depart","kind":"route","origin":{"coordinate":[-71.11902,42.37334]},"destination":{"coordinate":[-71.05524,42.35227]},"serviceDate":"2026-10-05","time":"08:00","maxWalkKm":1.2,"maxTransfers":3}
{"id":"harvard-south-arrive","kind":"route","origin":{"coordinate":[-71.11902,42.37334]},"destination":{"coordinate":[-71.05524,42.35227]},"serviceDate":"2026-10-05","time":"09:00","timePreference":"arrive_by","maxWalkKm":1.2,"maxTransfers":3}

vigo stream --city ./boston < queries.ndjson > results.ndjson

Each output line echoes its id; check every status, because one failed line does not end the stream. To serve applications over HTTP, start the engine's service and call it from a second terminal:

vigo serve --city ./boston --port 8080
curl --fail-with-body http://127.0.0.1:8080/v1/route \
  -H 'Content-Type: application/json' --data-binary @route.json

Open http://127.0.0.1:8080/ to read this guide from the running service, and send requests from the API console at the end of the HTTP API page. When you measure performance, keep the City build, a fresh process's first answer, and requests to a resident process separate.

Where next

• Practical workflowsArrival deadlines, pairwise journeys, and a complete baseline-versus-Scenario comparison.
• Core conceptsCity, Scenario, Query, Result, outcomes, and time.
• HTTP APIEndpoints, limits, status codes, and authentication.
• TroubleshootingBuild failures, blocked routes, time semantics, and stale observations.

VIGO has four nouns and three questions. Once these are clear, every interface behaves the way you expect.

GTFS + OSM ──build──▶ City ──(optional Scenario)──▶ Route | Matrix | Reach ──▶ Result

City

A City is a compiled mobility model built from GTFS and OSM. It is one complete directory, so its timetable, streets, and prepared query data cannot drift apart. Rebuilding from new source data creates a new City revision; existing Scenarios and Results stay tied to the revision that produced them. revisionId identifies the immutable build, builtAt records when it was made, and sources records the GTFS and OSM inputs.

A built City reopens without its raw GTFS or OSM files. Building prepares the street indexes and station-access state. The first query for a new set of active services prepares a timetable snapshot that later processes can reload; dates with the same active services share it, and --prepare-date creates it ahead of time. A new process still loads the files into memory, while a resident process keeps them ready.

Prepared files are tied to the source revision, routing policy, and format. Missing, stale, or incompatible timetable and access caches are rebuilt from the compiled City without importing raw sources again. Required street files must remain complete: restore or rebuild a City with missing or corrupt street indexes. Updating the underlying GTFS or OSM data requires a new build.

Scenario

A Scenario is an immutable set of changes applied to one City revision. Planned service changes apply to Reach. Supplied traffic applies to Drive Route and Drive Matrix, and a supplied realtime snapshot applies to transit Route; requests carry these as scenario, traffic, and realtimeSnapshot. Walking limits, departure times, and cutoffs remain query options. A complete alternative GTFS source is a new City revision, not a Scenario.

VIGO rejects unsupported combinations before computing. It never silently drops a change or moves a Scenario to a newer City revision. See Scenarios.

Query

Depart-at minimizes arrival time, then boardings, then walking. Arrive-by maximizes departure time; among journeys leaving at that boundary and arriving by the deadline, it minimizes boardings, walking, and actual arrival.

Reach is not accessibility. An accessibility measure also needs opportunities such as jobs, people, schools, or health care, and a stated way to combine them.

Result

A Result is the immutable answer to one Query: status, values, warnings, timing, the City revision, the Scenario if any, and the query output. Compare is an action on two compatible Results, not a fourth query. Keep the original request and the full Result together; the normalized query echo is useful for inspection but is not a complete archive of every option or supplied observation. See Read a Result.

Choose a supported combination

vigo capabilities describes the running build. Queries default to scheduled mode. Drive traffic needs both the traffic object and an explicit routingDataMode: "realtime"; VIGO never fetches a traffic provider. A visible vehicle, alert, or added trip is not itself a routing update.

Outcomes

• Public Route and Reach Results use ok or not_found. A completed Matrix is ok, with null for unreachable cells.
• Invalid or unsupported requests fail with an error and a nonzero exit code, or HTTP 4xx. Execution failures are errors too, never analysis Results.
• Python Results use ready and blocked; those names belong to the Python API.
• Studio background tasks report queued, running, ready, cancelled, or error.

Time

Service dates use the City's timetable timezone. A GTFS event at 25:10 belongs to the service date it was published on, even though it happens after midnight. Request clocks may exceed 24 hours, so always supply the exact service date with the clock. Realtime observation timestamps are a separate clock used only to admit or reject predictions.

VIGO keeps Build, Open, Compute, and End-to-end durations separate. Reusing an open process is useful runtime behavior; it does not hide or replace query computation.

These recipes start from the quickstart City, ./boston, and its coordinates. Each JSON block is a complete request to save under the filename shown. Replace the date with one your feed covers.

Choose a query

The support table shows which modes and supplied states each query accepts.

Explain one journey

Save journey.json:

{
  "origin": {"coordinate": [-71.11902, 42.37334]},
  "destination": {"coordinate": [-71.08337, 42.32978]},
  "serviceDate": "2026-10-05",
  "time": "08:00",
  "mode": "transit",
  "maxWalkKm": 1.2
}

vigo route --city ./boston --request journey.json --output journey-result.json

Check status, then the chronological journey.legs. Walking competes with transit, so a short trip can return a walk; set requireTransitRide: true to require a boarding, or "mode": "walk" to request walking alone. A not_found Result can reflect the date, timetable, access network, or constraints. It does not mean the places are physically disconnected; Troubleshooting lists the checks in order.

For several journeys at the requested time, add "alternatives": 3. The default pareto ranking keeps only genuine trade-offs between arrival, boardings, and walking; "alternativeRanking": "ranked" lists the earliest distinct journeys even when one beats another in every respect. See alternative journeys and journey windows.

Reach one destination by a deadline

Save arrival-matrix.json:

{
  "origins": [
    {"id": "harvard", "coordinate": [-71.11902, 42.37334]},
    {"id": "central", "coordinate": [-71.1035, 42.3654]}
  ],
  "destinations": [
    {"id": "destination", "coordinate": [-71.08337, 42.32978]}
  ],
  "serviceDate": "2026-10-05",
  "time": "09:00",
  "timePreference": "arrive_by",
  "includeJourneys": true
}

vigo matrix --city ./boston --request arrival-matrix.json --output arrival-matrix-result.json

Every pair shares the deadline. durationsSeconds[origin][destination] runs from the latest feasible departure to the deadline, so it can include waiting at the destination; the matching journeys entry gives the actual modeled departure, arrival, walking, waiting, and transfers. Set includeJourneys to false when only times are needed. A shared destination and deadline share one reverse search, and a shared origin and departure share one forward search. Split larger jobs by shared time and options; see Matrix for limits.

Test a planned service change

Save baseline-reach.json:

{
  "origin": {"coordinate": [-71.11902, 42.37334]},
  "serviceDate": "2026-10-05",
  "time": "08:00",
  "maxWalkKm": 1.2,
  "cutoffsMinutes": [15, 30, 45],
  "extentRadiusKm": 6,
  "rasterSize": 48
}

Save alternative-reach.json with the same origin and surface settings plus a Scenario:

{
  "origin": {"coordinate": [-71.11902, 42.37334]},
  "serviceDate": "2026-10-05",
  "time": "08:00",
  "maxWalkKm": 1.2,
  "cutoffsMinutes": [15, 30, 45],
  "extentRadiusKm": 6,
  "rasterSize": 48,
  "scenario": {
    "id": "direct-service",
    "name": "Illustrative direct service",
    "services": [{
      "operation": "add",
      "name": "Direct service",
      "stops": [
        {"label": "Origin", "coordinate": [-71.11902, 42.37334]},
        {"label": "Destination", "coordinate": [-71.08337, 42.32978]}
      ],
      "headwayMinutes": 10,
      "startMinutes": 420,
      "endMinutes": 600,
      "averageSpeedKph": 20
    }]
  }
}

The speed, headway, and operating span are illustrative. The example uses the defaults of bidirectional service, distance-estimated timing, and 0.35-minute dwell. It does not establish a drivable alignment, achievable running time, vehicle requirement, or service plan; Scenarios explains how to specify a real proposal.

Run both, then compare the saved Results with the compiler:

vigo reach --city ./boston --request baseline-reach.json --output baseline-result.json
vigo reach --city ./boston --request alternative-reach.json --output alternative-result.json
vigo-build compare --before ./baseline-result.json --after ./alternative-result.json \
  --output ./reach-change.json

Compare uses the retained surfaces. counts splits cells reachable in both into faster, slower, and unchanged, and counts newly and no-longer-reachable cells separately; a negative meanChangeSeconds means faster modeled travel among the comparable cells. Read all the counts together. A larger area is not a population benefit: an accessibility study also needs opportunity data, a spatial assignment method, and an explicit measure. The engine's vigo compare takes both Results in one request; see Compare saved Reach results.

Investigate live service

In Studio, start in Network: check the observation time and reporting coverage, then choose a route in Routes. Compare scheduled and predicted events at the same stop, and inspect a vehicle's position separately from its stop-time predictions. With a connected model, the service briefing can interpret the retained evidence; its explanation remains subject to review.

Use Route → Realtime to query supported, matched predictions. A vehicle on the map, an alert, or an added trip in Trip times does not by itself make that service available to routing. See Network and Routes and realtime admission.

For a reproducible analysis, use an exact date and time in Scheduled mode. For an incident review, retain the observation, identity, coverage, and Result from the original investigation. Read a Result covers both.

A City is compiled once by vigo-build and then opened read-only by any number of engine processes, Python sessions, or compiler queries. This chapter covers inputs, build options, and the life cycle of a City. The quickstart shows a complete Boston build.

Choose inputs

Keep the original files, their checksums, and their acquisition date. Download URLs such as latest are not frozen datasets. GTFS support lists the source features VIGO reads and the ones it reports as unsupported.

Build options

vigo-build build --gtfs feed.zip --osm region.osm.pbf --output ./city
vigo-build inspect --city ./city

Build is staged: a failed build preserves the previous City, and --replace restores the previous directory if publication fails. A successful replacement removes its temporary backup, so use a separate output directory when you need a rollback copy.

Raw import and street preparation happen at build time and are separate from query latency.

Large regions and low memory

Builds use disk-backed SQLite temporary work and compact numeric node lookups, report progress during long import phases, and respect container memory limits when deciding whether GTFS and OSM compilation may overlap. Import and native street preparation run in separate processes, so each stage releases its working memory before the next. Keep the output and temporary directory on a local filesystem (inside WSL, prefer the Linux filesystem to /mnt/c), and leave space for the source database, temporary sorts, and the finished City.

Regional native CCH preprocessing can still exceed 2 GiB without swap. Configure disk-backed swap for the build machine, or build on a larger machine and copy the complete City to the server: build memory and query memory are separate requirements. Street preparation must write the walking accelerator before the graph is sealed, so a City that could not open is never published.

Copy and load a City

A City contains network.json, routing/project.sqlite, prepared access artifacts, and an osm directory with street snapshots, access profiles, and CCH indexes. Exact member names can vary with the preparation version. Copy the whole directory, never just the SQLite files or the manifest.

The engine checks source identities, snapshot formats, station and access profiles, and required CCH members. It rejects blocking source features, missing or stale preparations, and an unexpected SQLite WAL. Complete a City through its compiler; do not delete WAL files to bypass validation. The engine reports timing.timetableSource: "prepared_snapshot" when it reuses a prepared timetable and "source" when it prepared one from SQLite for that process. Both use the same schedule.

Update a network

Treat a published City as immutable while any process has it open. Compile updates into a new directory, start another service against it, verify readiness and a known query, switch traffic, and then stop the old service. The engine has no upload endpoint, source downloader, or hot reload. See Upgrade and rollback for version changes.

Scenario collections

When you compare several timetables over one street network, build a scenario collection: one shared street graph, several transit scenarios, and a default. See Shared scenario collections for the source manifest and residency rules.

A City can contain several static GTFS feeds and several GTFS-Realtime endpoints. Static feeds supply the scheduled network; live feeds supply observations and predictions for it and never replace the timetable.

Build a City from multiple GTFS files

In Studio, open City → Data sources and add each GTFS ZIP. VIGO imports each source, then builds the combined routing store. Add an overlapping OSM PBF for walking, driving, and coordinate-based transit access, and wait for preparation to finish before querying.

With the compiler, repeat --gtfs and give each input a stable, unique scope:

vigo-build build \
  --gtfs ./rail.zip --gtfs-scope rail \
  --gtfs ./bus.zip --gtfs-scope bus \
  --osm ./region.osm.pbf \
  --output ./city

A scope identifies a source feed, not a route number. The merged store namespaces stops, routes, trips, services, and transfer references so identical IDs in different feeds cannot overwrite one another. Use the same scope names when you rebuild the same sources. Removing a source in Studio rebuilds the surviving combined store.

Before combining feeds:

• Use compatible service dates. A trip is usable only when its own calendar and exceptions activate it for the requested service day.
• Keep agencies in one timezone. Cross-timezone routing stores are rejected.
• Avoid importing two editions of the same agency timetable as separate networks unless that duplication is intentional.
• Retain declared transfers and verify street coverage. Close coordinates alone do not prove a usable station connection.

Connect multiple GTFS-RT endpoints

1. Open City → Data sources → GTFS-RT live feeds, or feed settings in Network.
2. Paste an endpoint URL and choose what it contains. A combined endpoint may contain several entity types.
3. Select its matching Timetable when the City has several static sources.
4. Choose Add feed for each additional endpoint, then Connect live.
5. Expand Feed status to inspect individual failures and freshness.

Live-feed requests use { "sources": [{ "url": "https://operator.example/trip-updates.pb", "kind": "tripUpdates" }] }. The old top-level url and urls formats are rejected; reconnect those saved connections through the feed editor. A single MBTA endpoint no longer implicitly enables the other two.

Trip Updates can be connected without Vehicle Positions. The MBTA preset fills three public endpoints; select the MBTA timetable when you use it in a combined City. A failed endpoint does not discard successful ones. Reimporting or merging a timetable invalidates the retained observation until a fresh fetch binds to the new City, and old records from a failed endpoint are not carried into a new snapshot.

Studio allows up to 16 distinct endpoints. Repeated URLs for the same timetable are fetched once, and assigning one URL to conflicting timetables is rejected. A refresh has a 30-second overall deadline, a 20 MB per-feed limit, and a 40 MB combined limit. Batches also reject more than 200,000 entities or 500,000 stop predictions. At most four downloads run concurrently, and oversized or failed sources are disclosed individually.

The declared type is descriptive: every supported entity present in the protobuf is decoded. A source timestamp and timetable identity travel with each record. Unscoped IDs match only when unambiguous; a bare trip ID never resolves by choosing the first agency.

Supply observations to the engine

Neither command-line runtime opens feed URLs. A Route request can carry a retained, normalized realtimeSnapshot with routingDataMode: "realtime". In a combined City, each record can carry sourceScope equal to its build scope, alongside the original tripId, sourceFeedTimestamp, service date, and stop predictions. A single-source City uses raw GTFS IDs; omit sourceScope there. The realtime input reference lists every record field.

Keep source timestamps intact. Changing a capture's timestamps to make it look current changes the input and is not a replay of that observation. A repeated snapshot ages out of the routing cache.

A collection serves several transit scenarios against one immutable street graph. Prepare it with node public/vigo.mjs build-scenarios --spec scenarios.source.json --output scenario-set, then point vigo serve --city scenario-set or vigo stream --city scenario-set at the result. Each request selects a scenarioId; omission selects defaultScenario. The one-shot CLI also accepts --scenario ID.

For wheelchair routing, add "wheelchair": true to the source specification or pass build-scenarios --wheelchair. Every member and the shared street graph then use wheelchair-strict-v1; unknown accessibility is excluded. Wheelchair collections require streetModes: "walk". Conflicting CLI/spec values and non-boolean specification values are rejected before compilation. Use a separate regular collection when both profiles are needed.

{
  "schemaVersion": "vigo.scenarios.source.v1",
  "name": "Regional alternatives",
  "osm": { "path": "region.osm.pbf" },
  "streetModes": "walk",
  "prepareDates": ["2026-10-05"],
  "defaultScenario": "baseline",
  "maximumResidentScenarios": 2,
  "scenarios": [
    { "id": "baseline", "name": "Baseline", "feeds": [{ "path": "baseline.zip", "scope": "agency" }] },
    { "id": "proposal", "name": "Proposal", "feeds": [{ "path": "proposal.zip", "scope": "agency" }] }
  ]
}

Source paths are relative to the manifest. Optional sha256 values pin each input. The compiler prepares street data once and creates relative references to it. Move the collection as one directory. Its checksum inventory records physical files once. prepareDates precompiles up to 32 service dates, reusing identical service sets; other dates remain queryable through the source timetable. A single-City build accepts repeated --prepare-date options.

Prepare a separate wheelchair City with the preparation CLI:

vigo build --gtfs feed.zip --osm region.osm.pbf --output wheelchair-city --wheelchair

The Engine CLI and HTTP service use that City for Route, Matrix and Reach. Add "wheelchair": true to the request, or --wheelchair to an Engine CLI query. Omitting the option inherits the City's profile. Ordinary Cities reject a true request; wheelchair Cities reject false, Drive, realtime transit and query-time scenario overlays. Compile changed inputs into a new wheelchair City. Serve the prepared wheelchair City using the same serve --city wheelchair-city command and authenticated /v1/route, /v1/matrix and /v1/reach endpoints.

The wheelchair-strict-v1 profile requires GTFS wheelchair_accessible=1 for vehicles and wheelchair_boarding=1 for boarding/alighting, including published parent inheritance. An accessible vehicle can pass an inaccessible stop without boarding or alighting. Unknown values are excluded. Search considers accessible alternatives directly, including later vehicles; it does not filter a completed unrestricted journey.

OSM ways require wheelchair=yes and ordinary pedestrian permission. Steps, escalators, mapped inaccessible or limited nodes, raised kerbs, unverified barriers and conditional accessibility are excluded. Published widths below 0.9 m and inclines above 8.3% are excluded. Untagged shape vertices inherit the way's accessibility. These are fixed profile limits, not a personalized chair model.

Station paths require either a positive published wheelchair_traversal_time (the MBTA extension) or step-free mode with published width at least 0.9 m, slope at most 0.083 in magnitude and a traversal cost. Elevator paths do not require slope. Explicit stairs and escalators remain excluded even if a contradictory wheelchair time is present. Direction is preserved. Missing paths do not generate parent-station shortcuts. Generic transfer recommendations do not establish accessible paths. For transit access, station platforms are reached from declared accessible entrances and paths, rather than snapped directly from the street.

Every successful or no-route response carries accessibility, including the profile and its limitations. Coordinate-to-network attachments are geometric; door-to-street access is not verified. Live elevator outages, temporary barriers and individual chair dimensions are not modeled. Strict source requirements can leave sparse coverage or no route. A no-route result is not evidence that no accessible real-world trip exists.

Source semantics: GTFS Schedule, MBTA pathways, and OSM wheelchair tags. The public synthetic regression is npm run check:wheelchair; it checks accessible alternatives through both CLIs and authenticated HTTP, as well as Matrix, Reach, reverse routing and profile mismatch rejection.

Route finds and explains travel between ordered points. This chapter describes how Route behaves; the Route request reference lists every field and default.

Inputs

A Route query selects:

• an origin, optional ordered waypoints, and a destination;
• transit, walk, or drive;
• an exact service date and local time;
• depart-at or arrive-by;
• a walking limit, an optional maximum number of transfers, and the objective;
• optional alternatives or a departure window;
• optional supplied observations supported by the selected mode.

Stop IDs are exact GTFS identifiers. Coordinate points are [longitude, latitude] and need streets in the City.

Walking and transit

Transit Route and Matrix compare a direct OSM walk by default, so a short coordinate trip can return walking when it arrives sooner. Set requireTransitRide: true to require at least one boarding, or select Walk mode to request walking alone. maxWalkKm limits each access and egress walk. Set allowLongWalk: false to apply the same limit to a direct walking alternative; otherwise maxStreetKm bounds the complete walk.

horizonMinutes sets the timetable search horizon (default 480, range 1–2880). For depart-at transit, boarding and alighting must happen at or before this boundary, including in alternative journeys; the final walk can finish after it. The horizon is therefore not a hard limit on door-to-door duration: comparisons with a total-duration cap must check the final arrival separately.

allowStreetTransfers (default true) controls walking connections between separate stops or stations. Turn it off to change vehicles only at the same stop or between members of one station, as identified by the GTFS station hierarchy. The engine removes cross-station walking edges before searching, including for arrive-by, realtime, and departure-window searches; access to the first stop and egress from the last remain available. Studio exposes this as Route options → Allow walks between stations or stops. It does not certify station-interior paths or free-transfer eligibility.

disableCache: true disables street-access frontier and walking-path caches while keeping the prepared City resident. Route answers are recomputed either way. The same flag applies to the wider access probes used to explain a blocked Route.

Transfers and time reserves

maxTransfers accepts integers from 0 to 31: 0 permits one boarding and 1 permits two. Omit it for no additional cap. Staying aboard the same trip is not a transfer. The cap constrains the native search, including alternatives and arrive-by, so a slower feasible route is found when the unrestricted winner exceeds it. A finite cap with ordered transit waypoints is unsupported.

minimumTransferBufferMinutes (integer 0–60, default 0) adds time before each subsequent boarding, after any transfer walk and the feed's own minimum transfer time. It is charged once per transfer, including a change at the same stop, and never delays the first boarding, the final egress, or staying aboard. arrivalBufferMinutes plans an arrive-by query against an earlier deadline. Both are timetable feasibility constraints, not delay predictions; see Time reserves.

The engine adds no implicit boarding buffer. Same-stop changes honor published GTFS minimum transfer times and forbidden transfers. Explicit transfer edges keep their durations without an added margin or a 60-second floor, and a published platform-to-platform transfer rule takes precedence over the station walking fallback.

How a journey is chosen

VIGO's objective is earliest_arrival. Equal-arrival journeys prefer fewer boardings, then less walking, then a stable final order; there is no undefined "balanced" preference. Arrive-by first maximizes departure time; among journeys leaving at that boundary and arriving by the deadline, it minimizes boardings, then walking, then actual arrival. A slightly later on-time arrival can therefore avoid unnecessary transfers.

If the reverse boundary cannot be materialized at first, the engine reconstructs a forward witness at the same departure from the complete access frontier. A remaining mismatch is a query error; an earlier feasible departure is never reported as the latest. An independently verified direct walk may dominate the reverse transit bound.

Ordered transit routes can walk any segment, including the whole journey. Selection compares complete journeys by arrival (or latest departure), then boardings and walking, so a later walk to a waypoint can replace a short ride when both catch the same onward vehicle. Up to eight partial journeys are retained at each waypoint and up to five complete choices are returned; this bounded search does not enumerate every itinerary. requireTransitRide: true requires a ride on every segment.

Alternatives and windows

alternatives (0–9) asks a depart-at transit Route for more journeys at the requested time; both runtimes return the same list. A departure window instead samples nearby departures: the engine's windowMinutes searches later departures or earlier deadlines, while the compiler's departureWindowMinutes (±0–30) is a centered depart-at profile. Sampled windows are not continuous timetable profiles. See Alternatives, via points, and departure windows.

Result and diagnostics

The public vigo.route.v1 Result contains status, a journey with chronological legs and durations in seconds, warnings, quality, and meta. A not_found Result is a completed answer with journey: null and an access reason when one is known. Read a Result defines every public field.

For a detailed diagnosis, request diagnostics: "trace" and read the internal result under trace. Access failures carry endpoint-specific accessAvailability:

• outside_selected_budget: an access candidate exists at a larger walking limit. The suggested limit does not guarantee a complete itinerary; streetPathVerified records whether its path was verified.
• street_access_unverified: nearby stops exist, but the bounded street search did not verify access. nearestStop.distanceKind: "straight_line" describes proximity, not walking distance.
• none_within_probe: no access candidate was found within probeWalkKm. This is a bounded result, not proof of disconnection at every distance.
• diagnostic_unavailable: the explanatory probe failed, reported as access_diagnostic_unavailable.

The diagnosis never raises the walking allowance by itself. Blocked plans keep searchLimits for walking, horizon, transfers, and the transit-ride requirement, including horizonScope: "timetable_scan". no_path means no scheduled itinerary under those constraints on the selected date; changing a constraint requires a new query.

Stations, access, and geometry

Anonymous coordinate endpoints and physical GTFS stops use the same nearest-street attachment in Route and Matrix. A parent station does not provide free movement between all its platforms. Declared station paths keep their direction and time; their complete time and distance frontier is prepared once and then filtered against each endpoint's remaining walking budget. Interior pathway nodes do not create extra street entrances.

When GTFS omits traversal_time, the walking policy prices the declared pathway length, or the distance between stop coordinates if length is also absent. Stairs with a stair count and fare or exit gates use labeled estimates described in walking evidence, floored by any available walking distance. A missing time is never a zero-time link. Endpoint walks that use a station path expose accessCost.street and accessCost.station separately, including directed stopIds and source types; this supports a source-data audit, not certification of physical station access.

The walking limit covers each complete, continuous access or egress walk; a transfer walk cannot extend the final egress beyond that budget. Street transfers use declared entrances and directed station pathways, composed around at most one external transfer edge. A repeated station in a ride sequence is reported but not rejected, because a scheduled loop or a forbidden platform change can require it.

A coordinate that snaps to the street graph can carry an endpointConnector on its first or last walking leg. Its coordinates and distance describe the snap already included in the leg's cost, with source: "coordinate-snap" and streetPathVerified: false. A connector is not evidence of a mapped or legally traversable street. For geometry materialization and identifier internals, see itinerary geometry.

Matrix calculates travel time between sets of origins and destinations in one request, from a shared departure time or to a common arrival deadline. Request journeys only when you need their steps. The Matrix request reference lists every field.

Send a matrix request

{
  "origins": [{"id": "home", "stopId": "A"}],
  "destinations": [{"id": "work", "stopId": "B"}],
  "serviceDate": "2026-10-05",
  "time": "08:30",
  "timePreference": "arrive_by",
  "mode": "transit",
  "includeJourneys": false
}

Replace A and B with exact stop IDs in your City, or use "coordinate": [lon, lat] points; Walk and Drive matrices require coordinates. The quickstart has a complete four-pair Boston example.

Read the result

durationsSeconds[originIndex][destinationIndex] gives each pair's elapsed time, and the ordered endpoints are echoed in query. A null cell means unreachable, never a zero-minute journey; a completed matrix can contain both. With includeJourneys: true, journeys has the same shape with a journey or null per pair. Add includeGeometry: true for path geometry; it requires journeys and performs no extra timetable search.

For arrive-by, a scalar duration is the deadline minus the latest feasible departure. A nested journey reports its actual arrival and may be shorter if it arrives early. Use the journey to separate travel from waiting at the destination. Public durations are seconds; minute-valued rows and search counters appear only in explicitly requested trace output.

Choose constraints

The Route rules apply: a feasible direct walk competes unless requireTransitRide: true, maxWalkKm bounds endpoint walking, maxTransfers accepts 0–31, and horizonMinutes bounds the timetable search rather than the door-to-door duration. allowStreetTransfers, minimumTransferBufferMinutes, and arrivalBufferMinutes behave as described under Route.

Transit Matrix is scheduled. Drive Matrix can use a supplied traffic snapshot with routingDataMode: "realtime"; it never fetches a provider or models traffic changing during a journey. See Street routing.

Share work across pairs

Results keep input order, including repeated endpoints. The compiler accepts up to 100,000 pairs in a 16 MiB request; the engine accepts up to 65,536 pairs in an 8 MiB request. Group work by shared endpoint, date, clock, and constraints:

Request scalar output when only times are needed. Journey queries also share boarding rounds within each endpoint group, so tied journeys can differ from Route's stable order while satisfying the same objectives. disableCache: true bypasses endpoint-frontier caches while keeping same-request sharing, loaded City data, and immutable street indexes; it does not clear the operating system's page cache. Service benchmarking shows how to measure full caller wall time.

Reach finds the streets and areas reachable from one origin within a time budget, by scheduled transit with walking or by walking alone. It does not measure access to jobs or people unless your analysis adds those opportunities. The Reach request reference lists every field.

Send a Reach request

{
  "origin": {"coordinate": [-71.11902, 42.37334]},
  "serviceDate": "2026-10-05",
  "time": "08:00",
  "mode": "transit",
  "cutoffsMinutes": [15, 30, 45],
  "extentRadiusKm": 6,
  "rasterSize": 96,
  "surfaceSampling": "street"
}

vigo reach --city ./boston --request reach.json --output reach-result.json

mode: "walk" requests walking-only Reach and needs no service date. Drive, arrive-by, and realtime Reach are unavailable. Planned transit changes use transit with street sampling.

Set the analysis resolution

The extent sets the analytical grid; it is not a maximum trip distance. Time budgets, walking limits, and the network decide what is reachable. Keep extent, resolution, sampling, and constraints identical when comparing results.

Choose the output

The default reachFormat: "full" returns the requested grid and the full reached extent. surface.valuesSeconds is row-major from the northwest corner, and null means unreached; read its bounds and dimensions with the values. fullSurface describes the separate full extent when available.

areas are GeoJSON polygons around reachable cells, preserving holes and islands. contours interpolate the sampled times and close at the grid edge and no-data boundaries; diagonal-only cells remain disconnected. The raw raster stays the reference for numerical analysis. For a map, request reachFormat: "map" to receive only the full reached-area polygons and their bounds, without raster values, stop lists, or duplicate contours; map output cannot be compared.

For network evidence, add includeStreetEdges: true (--street-edges on the command line) to the full output. Returned directed intervals keep their explicitly named units. See Reach output for raster ordering and edge decoding.

Compare with R5 and OTP

Use surfaceSampling: "cell-center" for a coordinate-destination surface. The default street mode records the earliest reached street portion in each cell and leaves cells away from reached edges empty; a filled street cell does not establish a route to its center. Area metrics sum sampled cells and do not measure physically walkable land.

When comparing engines, match the origin, service date, departure time, modes, walking and transfer rules, cutoff, extent, and grid resolution before drawing polygons. VIGO Reach evaluates a fixed departure. Conveyal's R5 can aggregate a departure window at a chosen percentile, and OTP's Travel Time API provides a departure-time snapshot; match the temporal statistic first. VIGO raster values are seconds, while requests use cutoffsMinutes.

For quantitative agreement, compute travel times at the same coordinates with Matrix, then classify them at the same cutoff. A longitude/latitude grid and a Web Mercator grid do not share cell centers. Compare contours separately from cell polygons, and check station entrance costs, boarding slack, and GTFS transfer minimums in representative journeys. For a Transit Matrix control that matches Reach's walking budget, set requireTransitRide: false and allowLongWalk: false. See Conveyal's isochrone methodology, OTP's Travel Time API, and the GTFS minimum-transfer rules.

Inspect a destination in Studio

After running Reach in Analyze, click a destination to see its map estimate and request a journey there; with the map focused, press Enter to inspect its center. The journey keeps the analysis origin, date, departure time, timetable selection, and walking and ride limits. Expand Show journey for the walking and transit legs. A missing raster sample does not by itself mean no journey exists.

Destination journeys use scheduled service and the City's routing walking speed. Planned service changes affect the scenario map estimate but are not reconstructed in the destination journey; the panel labels the difference.

Compare service changes

Run a baseline, then a planned Scenario with the same origin, clock, date, walking assumptions, sampling, and grid, and retain both Results. Scenarios explains exclusions and added service; Compare saved results explains the counts. A polygon describes modeled network reach. It does not certify entrance access, wheelchair connectivity, pedestrian permissions, or observed reliability; keep the walking evidence and known limits with the analysis.

A Scenario is an immutable set of changes tied to exactly one City revision. It may contain planned transit service changes, one live transit state, or one supplied traffic state. Walking limits, speeds, departure times, and cutoffs stay query options.

Scenarios never edit the imported GTFS or OSM, and a complete alternative feed is another City revision. Drawing geometry in an editor creates no computational change until it is attached to a valid service edit. Several nonconflicting planned changes may coexist; conflicts need an explicit resolution. A Scenario never moves to another City revision, and expired live state cannot be queried.

In VIGO 0.5.2, planned service changes apply to Reach, supplied traffic to Drive Route and Drive Matrix, and supplied realtime predictions to transit Route. Transit Matrix and Reach remain scheduled. Unsupported combinations are rejected with an explanation. The Scenario request reference lists every field.

Planned service

A planned service change states what changes and supplies enough to run it: ordered stops, travel-time assumptions, and a departure schedule. Edits to existing branches keep their GTFS trips by default; new service specifies frequency and operating hours. A Reach request can include this scenario:

{
  "origin": {"coordinate": [-77.05, 38.90]},
  "serviceDate": "2026-07-15",
  "time": "08:00",
  "scenario": {
    "id": "crosstown",
    "name": "Crosstown service",
    "services": [{
      "operation": "add",
      "name": "Crosstown",
      "stops": [
        {"label": "West", "coordinate": [-77.05, 38.90]},
        {"label": "East", "coordinate": [-77.03, 38.91]}
      ],
      "headwayMinutes": 10,
      "startMinutes": 300,
      "endMinutes": 1500,
      "averageSpeedKph": 22
    }],
    "excludedRouteIds": ["route-to-remove"]
  }
}

operation is add, augment, or replace. excludedRouteIds removes selected scheduled route variants for the Scenario.

Replace a branch and keep its trips

replace defaults to scheduleMode: "preserve-trips" and needs sourceRouteId, sourcePatternId, and selected-branch scope (routeScope: "pattern", or omitted when a pattern is supplied). Studio and the compiler load the trips active on the query's service date, including calendar exceptions and departures after midnight. Each affected trip produces exactly one replacement, keeping irregular gaps, per-trip running times, dwell, and pickup and drop-off restrictions. Editing stops never adds departures or reverse service. Older replacement requests use the same default: headway and hour fields are ignored unless frequency mode is selected explicitly.

For a branch that keeps its trips, road geometry distributes each trip's original A → B running time among the edited gaps. Original dwell remains at retained stops, and addedStopDwellMinutes (default 0.35) adds dwell at inserted stops; removing an intermediate stop removes its dwell. The first retained GTFS stop anchors departure timing: a preceding extension departs earlier, and later edits shift downstream times. At least one original stop must remain, with baselineStopId or baselineStopIndex identifying moved stops and repeated visits. An extension requiring a departure before the service date is rejected. These are modeled timing changes, not a vehicle or crew scheduling check.

Set a frequency instead

To change the timetable deliberately, use scheduleMode: "frequency" with headwayMinutes, startMinutes, and endMinutes; Studio calls this Departures → Set frequency and hours. This mode can replace a whole route, and add and augment use it by default. New lines use segmentDistancesKm and averageSpeedKph for road timing, plus dwellMinutes; segment arrays have one value per stop pair. Reverse service is an explicit choice in frequency mode and is never inferred from a shared route name.

Edit a shared edge in Studio

Selected branch only keeps a change on the chosen pattern. All branches serving this exact A → B edge applies one inserted gap to every occurrence of that ordered stop pair within the same feed and public route, but not to the reverse B → A edge. The editor lists the affected branches before running. This scope needs complete branch analysis and one inserted gap; use selected-branch scope for moved stops, extensions, or several gaps. Repeated stop visits keep their own positions and published runtimes, and overlapping replacement services are rejected. Studio requires a completed road path before running a road-following Scenario.

Compare the change

Run a baseline Reach and a Scenario Reach against the same City, origin, date and time, walking policy, cutoffs, and grid, save both, and compare them. Test a planned service change has complete paired requests. Compare reports after-minus-before changes for cells reachable in both surfaces and counts newly and no-longer-reachable cells separately. It checks grid compatibility but not every experiment setting, so read Compare semantics before attributing a mean change to the Scenario.

Route can use supplied GTFS-Realtime Trip Updates. This chapter explains how predictions are admitted and how to read the outcome; the realtime input reference lists the snapshot fields.

Two modes, one engine

Route exposes routingDataMode: "realtime" | "scheduled", shown in Studio as Realtime and Scheduled · Research. The command-line runtimes default to scheduled and use a supplied realtimeSnapshot; they never fetch feeds. The compiler also accepts --data-mode realtime|scheduled.

Scheduled research requires an explicit service date and time. The server removes realtime and traffic observations before processing, enforces the exact date, and disables date substitution. Studio keeps the selected date and time and ignores feed polling in this mode; live refreshes, expiry checks, and mode changes cancel obsolete realtime requests, and switching modes never shows the other mode's old result.

Both transit modes use the same native algorithms, stop identities, walking and transfer policies, and coordinate search; only the timetable presented to the engine differs. Transit Matrix and Reach remain scheduled and reject realtime requests.

Results for an explicit mode include diagnostics.routingDataMode and routingDataProvenance: source timetable and street identity, service date and timezone, query time, walking and search settings, engine contract version, and a reproducibility key. Realtime results also identify the prediction snapshot, and ordered journeys reject changed data identities between legs. The manifest identifies inputs but does not archive them; retain the City, the VIGO build, the request, and the returned diagnostics to reproduce a result. The 0.4.2 method audit records earlier correctness repairs.

Shared timetable

A journey search compiles the complete supplied TripUpdate snapshot into a separate resident timetable. Within the explicit resource limits there is no endpoint-based selection, inspection pruning, or duplicate-stop overlay, and an oversized snapshot is rejected as a whole rather than truncated. Each valid matched update replaces its scheduled trip; canceled and deleted trips lose their ride segments; unreported trips keep scheduled times.

Depart-at, arrive-by, transfer limits, and departure-window alternatives all use this timetable with the existing native algorithms. A query freezes its observation clock, including recursive verification and window samples. The latest compiled snapshot is cached per immutable service kernel and invalidated when input or timestamp validity changes; scheduled queries never inherit predictions from an earlier request.

Admission and coverage

An update must identify an active trip on the selected service day and source scope. Ambiguous identities, contradictory duplicates, invalid timing, unsupported relationships, and stale observations are excluded and counted. Feed and record timestamps are checked independently: admission accepts timestamps at most 180 seconds old and at most 60 seconds ahead of the captured clock. Network tools may apply their own freshness policy first, keeping all rejection counts.

An unreported scheduled prefix may conflict with the first explicit prediction of an early-running trip. The resolver excludes that prefix only when all its departures and the first explicit prediction precede the frozen observation boundary, with no earlier explicit update or trip-level delay. pastPrefixTrips and omittedPastPrefixStops disclose the exclusion; it does not reconstruct past events or claim actual passage.

diagnostics.realtimeRouting identifies the snapshot and counts applied, canceled, stale, unmatched, wrong-date, duplicate, invalid, and unsupported records. coverage accounts for every supplied record, including those rejected before routing. partial means some updates were applied while others were excluded, and failedFeeds reports unavailable endpoints. A scheduled fallback is identified explicitly; compile or search failures never silently retry against scheduled service.

Processing a full snapshot is not a claim that every trip has a prediction. Added, unscheduled, replacement, and duplicated trips without a supported scheduled instance remain unsupported and disclosed. Vehicle positions and text alerts never invent stop-time predictions. Studio's added-service display is separate from routing admission.

Read the realtime status

For transit Route, read diagnostics.realtimeRouting.status together with its counts. routingDataMode: "realtime" records the requested mode; it does not mean that predictions changed the timetable.

coverage.complete concerns admission of the supplied updates; it does not measure the share of scheduled trips that report. A fully admitted cancellation snapshot can legitimately return no journey. routingDataProvenance.realtimeApplied counts both replacements and cancellations. Keep these fields with the answer; see Keep uncertainty with the answer.

Stop predictions and source versions

A trip-level delay propagates forward until a stop-specific prediction replaces it, and a prediction at an intermediate stop never becomes a delay for earlier calls. Absolute time takes precedence over delay; arrival and departure remain separate. NO_DATA resets propagated delay, and SKIPPED removes boarding and alighting while keeping through travel. Repeated stops need an unambiguous sequence, and out-of-order sequences are rejected.

Each decoded record keeps its endpoint, source timestamp, and static-feed scope. VIGO does not compare GTFS-RT feed_version with static feed_info.feed_version, so connect the matching timetable edition yourself. A missing Trip Update means no reported prediction, not verified on-time operation.

Resource admission is separate from semantic coverage. Downloads are bounded, the decoder rejects feeds above 100,000 entities or 500,000 stop predictions, and native reconstruction checks its estimated memory against the timetable budget. Over-limit data is rejected, never silently truncated.

Verification

npm run check:gtfs runs the full feed and routing suite, including more than 256 updated trips, 1,024 input records, and 4,096 updated stops, interior transfers, both time directions, cancellations, skipped stops, transfer limits, snapshot replacement, and timestamp expiry. check-realtime-scheduled-parity.mjs compares 1,536 paired engine queries against eight independently imported GTFS timetables containing the literal effective predictions. check-realtime-past-prefix.mjs and check-routing-data-modes.mjs cover excluded prefixes and observation isolation. These establish algorithm parity for the tested cases, not field ETA accuracy.

A City built with OSM supports Walk and Drive variants of Route and Matrix, plus directed walking access for transit. Walk uses the directed pedestrian graph; Drive uses the directed road graph with free-flow time unless the request supplies traffic weights or closures. VIGO never replaces a missing street path with a straight line.

Street Route needs coordinate endpoints and returns full geometry. Street Matrix returns scalar distance and duration per pair without reconstructing every path; it sweeps from the smaller endpoint set, and many-to-one requests use the reverse directed CCH metric while keeping each endpoint's access permissions.

Coordinate network attachment

A free coordinate first attaches to its nearest pedestrian vertex or reciprocal edge. If that attachment belongs to a component with no public transit-access anchor, the query can recover to the nearest anchored component within 80 m. This applies to arbitrary coordinates without place-name exceptions. The connector and partial-edge distance count toward walking time and limits, and returned geometry includes the charged connector. Anonymous Reach seeds use the same recovery.

Stops keep their prepared physical anchors. Recovery never adds a street edge or a stop-to-stop transfer between disconnected components, a mapped authorized terminal path takes precedence, and a restricted endpoint cannot use recovery to bypass its directed exit. An off-network connector is a modeling assumption, not evidence of a surveyed entrance or a barrier-free crossing; an isolated place with no eligible street inside the radius stays unreachable.

Authorized endpoint access

Builds default to public pedestrian access: access=private without a pedestrian permission, or foot=private, stays outside the public walking graph. For a population authorized to use internal roads at its own homes and destinations, build with --private-access=endpoints. In Studio, choose City → Street network → Pedestrian access → Authorized endpoints before adding or replacing the OSM PBF; choosing Public paths only and replacing the streets removes the overlay.

This City-wide modeling assumption permits mapped private streets only within the origin's or destination's attached internal street region. An exact directed search follows those streets and interior public islands up to the first public component with a transit-access anchor. The public middle of the journey and stop-to-stop transfers never enter private streets, all internal walking counts toward the same walking limit, and geometry follows the mapped edges. Walking wholly within one internal region is supported.

The private graph is stored separately, so public street queries are unaffected. network.json records the access model, and transit diagnostics report walkingAccessPermission: "authorized_endpoints". The option assumes endpoint authorization; it does not infer parcel ownership, gate hours, or missing OSM links. Explicit pedestrian prohibitions stay excluded, gates marked prohibited, locked, or with unresolved opening times gain no connections, and Street Reach follows the same rules at the origin and at reached destinations. Rebuild older Cities to apply street-store schema v6, which also excludes platform area outlines from the linear walking graph.

Supplied traffic

No traffic provider is connected by default. OSM supplies the baseline road graph and free-flow estimates, and live transit feeds are not a road-speed model. Driving results without an applied traffic snapshot must not be described as current traffic estimates.

Drive Route and Drive Matrix accept a top-level traffic object with routingDataMode: "realtime". A snapshot customizes the prepared directed road graph for one query: a fixed set of edge costs, not a forecast that evolves as a vehicle moves.

{
  "routingDataMode": "realtime",
  "traffic": {
    "source": "your-provider",
    "observedAt": "2026-09-26T12:00:00Z",
    "ttlSeconds": 300,
    "observations": [
      {
        "fromCoordinate": [-71.0625, 42.3570],
        "toCoordinate": [-71.0615, 42.3575],
        "speedKph": 12
      }
    ]
  }
}

Use the actual observation time and the coordinates of an observed directed edge. This fragment shows the schema; its values are illustrative. A full request also needs the mode and endpoints.

Read diagnostics.traffic.status, the matched and unmatched counts, and weightModel. Only applied establishes that supplied costs changed the model; no_matches and free_flow_equivalent do not establish current coverage. Coordinate matching is nearest-edge matching, not a validated provider conflation pipeline, and VIGO does not yet model every turn, signal, intersection delay, parking, or a future traffic trajectory. The traffic input reference lists every effect and limit.

VIGO supports explicit time reserves that change which journey is chosen. It does not yet estimate an on-time probability, a travel-time distribution, or a calibrated confidence interval: scheduled and admitted realtime event times are point estimates.

Use reserves in a routing request

Both are integers from 0 to 60 and default to zero. A positive arrival reserve needs a deadline at least as large as the reserve and a horizon exceeding it by at least one minute; the earliest departure stays the one implied by the original deadline and horizon. Transit via points reject a positive reserve because composing segments would apply it repeatedly, and Walk, Drive, Reach, and native operations reject a positive arrival reserve.

For Harvard Square to South Station, save reserved-arrival.json:

{
  "origin": {"coordinate": [-71.11902, 42.37334]},
  "destination": {"coordinate": [-71.05524, 42.35227]},
  "serviceDate": "2026-10-05",
  "time": "09:00",
  "timePreference": "arrive_by",
  "maxTransfers": 3,
  "horizonMinutes": 120,
  "minimumTransferBufferMinutes": 3,
  "arrivalBufferMinutes": 5
}

vigo route --city ./boston --request reserved-arrival.json

VIGO plans arrival by 08:55, allows departure no earlier than 07:00, and requires three extra minutes at each change. These numbers are illustrative preferences, not an MBTA delay estimate or a recommended threshold, and a tighter request can legitimately find no journey.

Route clocks and leg durations still describe the chosen timetable journey, and a Matrix scalar duration keeps its deadline-minus-departure definition, including the reserve. Keep diagnostics.timeReserves with the answer: it records the requested and planning deadlines, both margins, and calibratedProbability: false. Request diagnostics: "trace" to see it. A transfer reserve can absorb some lateness, but it does not model early departures, missed-connection recovery, capacity denial, cancellations, correlated delays, or uncertain walking and station access, and the final reserve alone does not protect intermediate transfers.

Calibrate probabilities before offering them

GTFS-realtime StopTimeEvent.uncertainty has no defined statistical meaning, and an omitted value means unknown. It must not become a standard deviation or a 90% interval without a validated, provider-specific model. See the GTFS realtime reference.

For a Boston calibration study, start with the MBTA LAMP exports and their data dictionary and TransitMatters Gobble. These are potential inputs; VIGO does not download or fit them. A credible next stage would retain historical forecasts and outcomes, match the exact feed revision and trip instance, estimate errors by route, direction, time of day, and lead time, and validate on later dates with coverage reporting. Same-vehicle and shared-corridor delays are correlated, so multiplying marginal transfer probabilities is not a journey probability. Probability-driven routing would need its own search and calibration contract.

Reproduce the implemented contract

Run node test/check-arrive-by-boundary.mjs after building the native kernel and npm run check:standalone after building the compiler. The public fixtures cover a changed selected departure, the exact reserve boundary, blocked outcomes, unchanged earliest departure, transfer-reserve combinations, matrices, invalid values, and repeated requests through both runtimes. They establish modeled feasibility, not measured on-time performance.

Route shows boarding prices from the imported GTFS feed. In Studio, expand the fare line for ticket names, payment methods, and the agency's fare link; JSON Results carry the same data in each transit leg's fare.

These are prices for a new boarding, not an optimized journey fare. Multi-leg results deliberately have no total, because joining legs, transfer discounts, passes, and existing tickets can change what a rider pays. A missing quote does not mean free travel, and path selection does not consider price.

Data and matching

The importer keeps fare tables and their route, station, agency, and calendar references in an optional fare_catalogs SQLite table. Catalogs travel with a City and stay separate when feeds are merged. Cities built before fares were added need their original GTFS reimported to keep fare data.

• Fares v2 takes precedence when fare_products.txt is present. Matching uses route networks, station areas, rule priorities, fare timeframes, and the default rider category; product names and media come from the feed. MBTA's transfer_only extension is honored, so a free-transfer product never becomes a free new boarding.
• Fares v1 supports flat, route, and origin/destination-zone boarding prices. Zone-traversal (contains_id) rules stay unquoted.
• Fare timeframes use the civil date and time at the validation stop, including its timezone, daylight-saving changes, times after midnight, and calendar exceptions. For a realtime-adjusted leg, the original scheduled stop sequence must be uniquely recoverable before timed rules apply.
• Explicit platform fare areas override inherited station areas. Ambiguous network assignments, conflicting products, missing references, and unsupported conditions stay unquoted, and an unreadable fare catalog never discards a computed route.
• Transfer totals, joined fare legs, pass selection, non-default rider eligibility, and fare-based optimization are not implemented.

Matching follows the GTFS Schedule reference. No agency prices or route-name rules are embedded in code; prices reflect the saved feed.

Performance

Fare lookup happens only after route selection, so no fare code runs inside routing, matrix, or Reach searches. Catalogs load by feed scope and are indexed once; quote, candidate, catalog, and scheduled-trip caches have explicit bounds and are released with their catalog. With cached catalogs, annotation performs no SQL. First-use parsing, serialization, and rendering still take time; measure them separately with node scripts/benchmark-fares.mjs FEED.zip STORE.sqlite YYYY-MM-DD report.json.

Verification

node test/check-gtfs-fares.mjs covers exact matching, missing data, published zero fares, invalid prices, transfer-only products, default rider categories, area inheritance, empty-rule semantics, priority rules, after-midnight date changes, time-window boundaries, scoped multi-feed import and merge, and non-mutating itinerary annotation.

Version policy

Public v1 schemas preserve required fields, their types, units, and meanings. Removing or renaming a field, changing its units, or changing a status meaning requires a new schema version. Additional optional fields may be introduced; clients should ignore unknown fields. trace, native kernel structures, and Studio's internal worker messages are outside this stability policy. Result schema versions are independent of prepared City formats.

The 0.5.0 public schemas replace the older result envelopes; there is no legacy-envelope adapter. See upgrading for the City rebuild and rollback procedure.

Reading a result

The CLI, resident stream, and HTTP services use one public result contract. Read status first: ok contains the result, not_found means no journey satisfies this request, and error means the request failed. A valid no-journey response exits 0 and uses HTTP 200.

Route returns schema: "vigo.route.v1", query, journey, and meta. Matrix and Reach use vigo.matrix.v1 and vigo.reach.v1. The schema version and meta.engineVersion are separate identities.

Interactive Route commands show a short itinerary. Pipes, --output, and --format json produce structured JSON; --format text explicitly selects the terminal view. Diagnostic details are available in JSON.

Journey

journey contains departureTime, arrivalTime, durationSeconds, walkingSeconds, waitingSeconds, ridingSeconds, boardings, transfers, and legs. Drive journeys also have drivingSeconds. Clocks are local service-day HH:MM:SS, including hours above 23. Durations are integer seconds, rounded at the public boundary; routing retains its original precision. Waiting includes the gaps before and between legs. It is not inferred to be a reliability margin.

Legs have type: "walk" | "transit" | "drive", from, to, clocks, duration, and available distance. Transit legs identify the route and trip. Stop, route, and trip references use { "feed": "mbta", "id": "70067" }; an unscoped feed is null. You can send an endpoint as { "stop": { "feed": "mbta", "id": "70067" } }. Older string stopId requests remain accepted.

Route includes available GeoJSON geometry on each leg by default, preserving the full source coordinate precision and vertex sequence. A transit line runs from the boarding stop through the aligned shape vertices to the alighting stop, and its distanceMeters is the length of that line. A walk that starts or ends off the street network reports the short connection as endpointConnector. Send includeGeometry: false or use --include-geometry=false for a smaller response without coordinate arrays. Matrix journey geometry remains opt-in with includeGeometry: true. Geometry describes the modeled path, not an observed vehicle trajectory or a guarantee of surveyed station interiors. Ordered journeys have a single ordered leg list.

Additional journeys appear in alternatives, which excludes the primary journey and duplicates and is omitted when none remain. alternativeSearch describes how they were found. Requested alternative journeys (alternatives, alternativeRanking) are available in both runtimes and report coverage: "requested_time". Standalone journey windows sample later departures or earlier arrival deadlines and report their sampling direction.

Transit legs carry a fare when the City publishes GTFS Fares v1 or v2 data for the ride. Both runtimes price legs with the same engine.

Keep uncertainty with the answer

quality.streetGeometry distinguishes verified street evidence from unverified geometry. quality.stationPath is source_path or inferred when station access is present. A verified street segment does not certify a complete entrance-to-platform path. components separates street and station access costs and identifies their source types. Transit quality.schedule: "timetable" means modeled timetable times, not observed punctuality or a guarantee that every source timestamp was measured.

Route warnings describe qualifications that affect the returned journey. Dataset/model limitations live in vigo info (Rust), vigo inspect (Node), or GET /v1/info; send includeLimitations: true when needed alongside a query. No warnings does not certify complete source coverage. Unsupported GTFS semantics remain documented in known limits.

Diagnostics

Use --diagnostics summary, a JSON diagnostics field, or ?diagnostics=summary. HTTP also accepts ?vigo_diagnostics=summary. Conflicting body and URL settings are rejected. trace is an unstable research/debug ABI: internal indices, sentinels, duplicate units, and raw candidate arrays intentionally remain there. Production clients should consume the public fields.

scannedDepartures is the engine's departure scan count; expandedTripRuns and relaxedStops are its reported expansion/relaxation counts. They are not interchangeable with network size or unique visited stops. Candidate counts count the returned endpoint candidate entries. Fields without instrumentation are omitted rather than fabricated. The Rust and Node runtimes return the same public result for the same request and City; summary and profile fields describe each runtime's own instrumentation and are not comparable across runtimes.

meta.computeUs retains the runtime's measured compute boundary, identified by computeScope: "query_dispatch_including_materialization": service-date activation, search, and result materialization. It excludes public formatting, final JSON serialization, HTTP queueing, and network transit. Profile scopes can overlap and must not be summed. Server-Timing reports measured serialization and compute; the Rust supervisor also reports queue time. Client wall time remains a separate measurement.

meta.requestId identifies a result; caller-supplied id is echoed. meta.queryFingerprint hashes the caller's request, with stop references canonicalized, and the City revision; output switches (id, diagnostics, includeGeometry, includeLimitations, reachFormat) are excluded. The same request has the same fingerprint in both runtimes. Equivalent requests written differently, for example time and timeMinutes, can hash differently. Supplied scenario and realtime content get separate fingerprints; retain the original inputs for reproducibility. Realtime admission/application evidence is retained when the runtime supplies it.

Matrix and Reach

Matrix returns durationsSeconds[origin][destination], with ordered endpoints in query. Unreachable cells are null, never zero. Optional journeys follows the same ordering. Arrive-by duration is the requested deadline minus latest departure; a nested journey can arrive earlier and have a shorter elapsed duration.

Reach returns surface.valuesSeconds, grid bounds and dimensions, cutoffsSeconds, GeoJSON contours/areas, and fullSurface when available. Cell order is unchanged: row-major, northwest first. Unreachable cells remain null. GeoJSON cutoff properties and explicitly requested street/node evidence retain their documented unit-labelled fields; these analytical evidence formats are separate from journey durations. Raw search chains are only in trace.

For a map, request reachFormat: "map". The result contains areas and bounds for the full reached extent, without raster values, stop lists or duplicate contours. Its polygons equal fullAreas in the default reachFormat: "full" response. Use the full response for grid comparisons and request includeNodes or includeEdges only with that format.

Compare saved results

Public saved results can be compared without rerunning routing. Changes are after minus before, in seconds. Route reports duration and transfer changes; Matrix and Reach report common, faster, slower, unchanged, newly reachable and no-longer-reachable counts. Means use only mutually reachable entries and are null when none exist. Matrix requires identical ordered endpoints; Reach requires the same grid. Callers must align other experimental assumptions.

For a source-data audit, request diagnostics: "trace" and retain the original witness under trace. Low-level native operations have a separate field reference.

Keep a reproducible run

Errors use schema: "vigo.error.v1", status: "error", and error.code / error.message. Handle stable codes and HTTP status, not OS error text. Keep the City, original query, executable version, supplied observations/scenario, and result together when retaining a reproducible run.

Untimed GTFS stairs and gates using routing estimates expose quality.stationTime: "estimated" on the walk. Their diagnostic provenance is gtfs_pathway_estimated; these costs are not published or measured traversal times.

Detailed wrapper transport

stream --stream-output=detailed sends a vigo.stream.detail.v1 envelope containing id, status: "ok", and trace, without constructing a second public result. The trace is the same complete internal result provided by --diagnostics=trace; it remains an unstable internal ABI. Envelope ok means execution completed: inspect the detailed result's routing status to distinguish a journey from a valid blocked outcome. Failures retain the standard vigo.error.v1 envelope and do not stop subsequent requests.

Clients must check capabilities.output.streamFormats for detailed before selecting this transport. VIGO-py negotiates it automatically and falls back to the full public trace response on earlier compatible runtimes. The default stream output remains the public result schema.

VIGO 0.5.0 enforces stop-transfer walking floors, OSM node restrictions, and explicit missing station coordinates. Both Node Engine and standalone Rust use the same prepared City data. Rebuild pre-0.5.0 Cities from the original GTFS and OSM inputs as described below.

Time and connectivity are separate

A GTFS transfer minimum constrains the time between services. It does not describe a physical path or permit arbitrarily fast walking. Before searching, VIGO prices each expanded stop pair at the larger of the published minimum and its distance divided by the configured walking speed, rounded up to a whole second. The distance is at least the straight-line separation of valid stop coordinates. That separation supplies a lower bound; a missing interior path remains unknown.

GTFS pathways describe directed station connections. An explicit traversal_time remains a source cost, including for lifts and moving walkways. If it is absent, VIGO derives a time from the available length and walking policy. A declared pathway supports the feed's connectivity model; it is not a current field measurement. When a station declares pathways and public entrances, coordinate access uses those entrances; snapping straight to a platform cannot bypass the station connections.

The walking floor enters preparation before boarding selection, so a depart-at query may choose a later connection and an arrive-by query may require an earlier departure. Route and both scalar and journey Matrix modes use those same costs.

Pedestrian permissions

The OSM importer reads tags on ways and their nodes, including packed dense nodes. It excludes foot=no, foot=private, and foot=use_sidepath, honors explicit pedestrian permission over generic access, and preserves directed pedestrian rules. A motor-vehicle one-way restriction alone does not prohibit walking in the reverse direction.

For nodes, impassable barriers and denied access exclude incident pedestrian segments. Ambiguous gates require explicit permission. Foot/access conditional rules and opening hours other than 24/7 are excluded because this static model does not evaluate their conditions. This conservative policy can reduce coverage, including approaches to a blocked barrier. Driving retains its separate permissions. See the OSM definitions of foot access and pedestrian direction.

What a returned route establishes

streetPathVerified concerns the prepared street graph; it is not independent proof of an entire door-to-platform walk. Free-coordinate snapping is returned separately as endpointConnector, with streetPathVerified: false. The walk's line still starts or ends at the requested coordinate, so a journey is drawn without gaps; its first or last segment is that connector. An assumed station interior has stationAccessStatus: "unverified"; a published transfer minimum does not change that status. Selected station costs and stop chains are exposed in accessCost when available.

An independent physical audit needs a continuous, directed source path, legal node/way access, and evidence for the links between the requested location, street, stop, entrance, and platform. A line near an OSM street is insufficient. Source gaps require better mapped entrances, agency pathways, or validated access links. Even complete source evidence does not establish current closures or observed travel times.

An interior GTFS node may omit coordinates. VIGO retains its declared pathway connections and stop ID but omits that node from displayed geometry, setting stationGeometryStatus: "incomplete". A line between the remaining known coordinates is schematic. If a source-timed pathway also lacks length and located endpoints, its distance contributes only a zero lower bound and the leg reports stationDistanceStatus: "lower_bound"; it is not measured zero-distance walking. When traversal_time is absent, stairs with a nonzero stair_count use one second per step and fare/exit gates use five seconds. These fixed routing assumptions are recorded as gtfs_pathway_estimated, retain stationAccessStatus: "unverified", and are floored by available distance at the configured walking pace. They are not measured or agency-published traversal times. Explicit traversal times take precedence. Other pathways without time, length, or distinct located endpoints remain excluded and reported as unpriced_pathways. The declared station topology remains in force, so exclusion cannot create a fallback shortcut. A feed-supplied connection alone does not certify its physical duration.

Upgrade and check

Build a new City with the current runtime and the retained raw GTFS/OSM inputs. Use the Boston quickstart and a new output directory, then open it with the engine as described in the engine manual. Keep the old City with its original runtime for reproducibility.

Street schema v4 cannot be upgraded by reopening a cache: its missing node restrictions require reimport from the original PBF. The current street schema is v6; it also excludes platform area outlines from walking links. Routing-store schema v3 distinguishes missing coordinates and pathway costs from genuine zeros and requires a fresh GTFS import. Transfer semantics v4 additionally requires reimport to recover pathway modes and stair counts discarded by earlier imports. Prepared access policy v9 connects street transfers to public entrances and composes their directed station pathways during preparation and prices travel between projections on the same street segment directly. Each boarding transfer can include at most one external transfer edge; the itinerary retains every original pathway segment. Declared pathways suppress invented parent-station shortcuts. Node Engine refreshes outdated timing preparations; standalone Rust requires current prepared data and rejects stale street, routing-store, or transfer-time policies.

Public regression checks use generated inputs and can be run from the source checkout:

npm run check:osm-pbf
npm run check:national-focused
npm run check:standalone

These checks exercise node barriers, access overrides, malformed node tags, pedestrian direction, physically feasible transfer selection in both time directions, scalar/journey matrices, and rejection of old prepared data. They test the implementation and declared input model, not the completeness of any agency's pedestrian map.

Open a JSON response from the VIGO engine, compiler, or HTTP API. The viewer shows its status and main answer, draws a journey timeline, a matrix table, or a Reach raster, and keeps the complete source JSON alongside.

Read the public fields

Route uses journey, Matrix uses durationsSeconds, and Reach uses surface.valuesSeconds or map-only areas. Durations are seconds and a null analytical value is unreachable. Keep geometry qualifications and warnings with the answer.

Choose or drop a file in the interactive viewer. Files are read on your device and never uploaded; the viewer accepts up to 25 MiB.

Python exports

Python's Result.to_dict() keeps its detailed, minute-valued payload. Use the Python Result reference to interpret those exports; this viewer accepts public engine schemas only.

No file selected.

VIGO models the City revision and query it is given. It does not certify real-world service, demand, safety, or operational feasibility.

GTFS

• Support is limited to the source features listed in GTFS support. Unsupported or malformed features are reported during the build.
• Missing published shapes do not prevent timetable routing but limit map geometry.
• Block-based in-seat continuation is not inferred.

Transit Route and Matrix

• Arrive-by Matrix durations include any wait between actual arrival and the deadline; use Route or Matrix journeys for actual arrival.
• Transfer and arrival reserves can change route selection, but VIGO does not compute calibrated arrival probabilities or delay distributions.
• A finite maxTransfers cap with ordered transit waypoints is unsupported.
• Station returns may be valid in the supplied timetable; they are flagged, not excluded.
• Without an explicit rule or declared pathway topology, platforms sharing a parent station use a transfer assumption of at least 120 seconds, floored by their coordinate distance at walking speed. These legs report transferSource: 'parent_station_fallback' and schematic geometry, not a verified station pathway.
• A street route to a platform coordinate does not establish an entrance-to-platform connection. Walks touching subway stops or platforms report stationAccessStatus: 'unverified' unless they carry a declared pathway with no estimated segments; streetSegmentVerified keeps the narrower OSM result. Untimed stairs and gates use explicit routing estimates (one second per step, five seconds per gate), marked gtfs_pathway_estimated. Scalar Matrix results do not carry this per-leg audit.
• Departure windows sample integral minutes; they are not continuous profiles.

Streets

• Walk and Drive depend on OSM coverage and directionality.
• Pedestrian attachment searches vertices within 160 m and projects onto reciprocal edges within 80 m. A missing attachment is not proof that no physical path exists.
• Platform polygons describe an area, not a walking line. Street-store schema v6 excludes their outlines from the walking graph; routing across polygon interiors is not modeled, and older Cities need a source rebuild.
• An anonymous endpoint on an unanchored fragment can recover to the nearest transit-connected component within 80 m, including the full connector cost. This adds no graph links and proves nothing about buildings, fences, water, or levels in between. See coordinate attachment.
• Authorized endpoint access is an opt-in build model; it does not establish individual permissions, gate hours, or missing connections.
• Drive does not yet model every turn restriction, signal, or intersection delay. Traffic must be supplied by the caller.

Realtime

• Realtime transit applies to Route only, and only with a supplied realtimeSnapshot and explicit realtime selection. Transit Matrix and Reach reject realtime requests. Vehicle Positions and Alerts do not change route costs or close services.
• Only FULL_DATASET feeds are decoded. Updates modify matched scheduled trips, remove CANCELED and DELETED trips, and omit SKIPPED calls. Added, duplicated, replacement, and unscheduled trips without a supported scheduled instance are unsupported for routing, though Studio can display them.
• Feed and record timestamps must pass freshness checks: up to 180 seconds old and 60 seconds ahead of the captured clock. Missing timestamps do not establish freshness. See realtime routing.

City reuse and platforms

• Copy the entire City directory; street indexes and prepared files are part of it. Executables are specific to an OS and CPU, while City data is portable across the supported 64-bit targets.
• Older Cities with ephemeral Drive CCH rebuild that hierarchy on fresh-process startup; rebuilding the City from source enables persisted Drive CCH.
• An incompatible timetable cache, a new active-service pattern, a changed walking policy, or an evicted snapshot requires preparation. Missing or corrupt required street indexes are errors; restore the complete City or rebuild it.
• Studio project settings, drafts, and live connections are local application state and do not travel inside a City. Studio cannot open compiler City directories in this release.

Scenario and Reach

• Planned transit service changes apply to Reach; supplied traffic applies to Drive Route and Drive Matrix. Other combinations are rejected.
• maxTransfers limits changes between vehicles in both baseline and scenario Reach; zero permits one ride, and walking never counts as a boarding.
• After the last ride, Reach follows the same declared station exits as coordinate egress, and a stop reached only by a transfer walk does not restart the walking allowance. Reach rasterizes reached street edges while Matrix evaluates destination coordinates, so their cells can differ under matching settings.
• Reach measures modeled travel time, not people, jobs, demand, welfare, observed behavior, or operational feasibility.

VIGO Studio puts Network, Route, Analyze, and City views over the same routing engine. It keeps its own project library and works offline once a City is imported.

Documentation and settings

Open Settings → Documentation from the City library or the sidebar to read this guide offline, in Studio's light or dark appearance. Press / to search; links to source files and external references open in your browser. Reading documentation does not open a City or prepare routing data, and the API schema download is bundled locally.

Open a City

Select a project from the Studio library and import GTFS and OSM. Rebuild when the source feed or street extract changes. Studio stores projects in its library format and cannot open the movable City directories built by the compiler in this release. Opening a City prepares walking for transit access and walking routes; the driving network opens when you select Drive. Background tasks shows preparation progress.

Network

Use Network for reporting coverage and briefings, and Routes for trip times, station boards, and line views. Route and station selection is shared across the tabs. Network and Routes explains playback, live timing, added service, and model connections.

Route

Plan

Pick an origin and destination on the map. Add point inserts a via point before the destination, up to eight points in total; click a row to repick it, use the arrows to reorder it, or remove it, and Reverse flips the sequence. You can also type a coordinate command in Search VIGO, such as route 38.90, -77.05 to 38.91, -77.03 at 08:00, then choose Plan this journey. The route form does not search place or station names.

Choose a travel mode. Realtime transit departs now; Scheduled exposes the date, time, and depart-at or arrive-by controls. Transfer caps are disabled while via points are present. Changing points or options updates the route, Rerun route submits the same coordinates again, and New route clears them.

Sort journeys by Earliest, Fewer transfers, or Less walking. Each card shows arrival, total time from your requested departure, transfers, walking, and its trade-off against the earliest arrival. Sorting keeps the selected journey and does not rerun the search; arrow keys, Home, and End select another journey, and Details opens its itinerary.

Save a journey

Choose a format beside Save in the journey details. JSON keeps the selected plan, diagnostics, and a summary separating the initial wait, journey duration, and total elapsed time. Markdown is a readable itinerary whose clocks can exceed 23 hours after service-day midnight. GeoJSON keeps leg geometry and its source when the complete path is retained. CSV records each leg's trip and service-clock times; clock_service_date names the midnight those minutes count from, and minutes can exceed 1440. Saving never reruns the query.

Save all beneath the journey choices keeps every completed alternative, including those beyond the five visible cards. Filenames include the service date, places, and export time.

Recent

Reopen recent Route Results for the current City revision. Each keeps its normalized request, status, warnings, and timing beside the journey.

Analyze

Reach

Choose an origin on the map, or use Choose origin to search imported stops by name or ID or enter coordinates. Run Reach, then switch between Reachable area, Reached streets, and cutoffs; changing the displayed cutoff reuses the retained result. See Reach for limits and bounds.

Compare

Studio's feed comparison runs Reach for each selected GTFS feed and shows the surfaces. City comparisons mark the first selected feed as the reference and show sampled-area and reached-stop differences at the selected cutoff. Scenario cases show the same measures against their baseline, together with faster or newly reached and slower or lost cell counts. Differences require the same origin, date and time, mode, sampling, and walking and transfer settings; cell counts are never subtracted across independent grids. To compare completed Results without rerunning them, use the compiler's compare.

Use Save beside Reach or comparison results for the full JSON, the selected cutoff's area geometry, or a CSV summary. total_processing_ms measures complete analysis processing, separate from native query timings; area_source distinguishes an exact-cutoff area metric from a display-raster calculation; reference_surface and reference_feed_id identify the baseline. Saving becomes available when the computation finishes.

Scenario drafts and the selected case are saved in Studio's local profile and restored when you reopen the same project and source revision. They do not travel with a City directory; reimporting GTFS or rebuilding the project starts a separate draft set. For a stop inserted on an A → B edge shared by several branches, the road path applies to each affected branch, and each branch keeps its own untouched shape and runtime. Use the engine, the compiler, or Python for Matrix queries.

City

Data sources

Open City → Data sources to review GTFS feeds, OSM coverage, counts, and warnings. To remove a source, select the trash button beside its row, check the name, and confirm Delete source. Removing a GTFS feed refreshes the combined timetable from the remaining feeds; removing OSM removes street routing and OSM-derived walking transfers until another import. The City, other sources, saved notebooks, and your original files are kept, and deletion is unavailable during import or preparation.

Preferences

Choose appearance, storage location, and map preferences. The default City folder is ~/Documents/Vigo Projects. On macOS, Studio does not scan or test-write the library until you choose Open library folder, when macOS may ask for permission. Locally rebuilt apps use ad-hoc signatures, so an updated build can need authorization again.

Local OSM is the default basemap. It draws main roads, rivers, lakes, and coastal water from the City's imported PBF in light or dark appearance, with no tile service, API key, or network connection; residential streets, paths, buildings, and labels are omitted to keep routes and analysis clear. Cities imported before the local map index need one fresh OSM import. Online OpenStreetMap and CARTO styles remain optional.

Studio troubleshooting

Playback shows no trips

Check the exact service date, calendar.txt, calendar_dates.txt, the selected direction and pattern, and whether the playback time falls between a trip's first departure and last arrival. A route-wide total is not the number of vehicles active at once.

An access path crosses a block

The access or egress line must come from OSM street geometry. Rebuild from current OSM data, confirm the point lies within coverage, and inspect the selected street leg. Studio never replaces a missing street path with a straight jump.

A date is rejected

Use an exact YYYY-MM-DD date inside the feed's active service range. Studio applies the same calendar rules as the command line.

A loading indicator is not advancing

Background tasks show measured bytes or records for steps with a known total; the percentage belongs to that step, not the whole import. Work without a total shows an indeterminate bar, elapsed time, and the age of the last update. If updates pause, use Reconnect to task: the task may still be running, so check its status before importing the same source again. Confirm that the City folder is readable and writable and that macOS has granted access.

Open Network in VIGO Studio to inspect the selected City's timetable, live reports, and retained briefings. The workspace has Network and Routes tabs; use Route for journey planning and Analyze for Reach.

Read the evidence

The same map can show several kinds of evidence. Read the source and observation time before interpreting a change.

None of these is a verified history of actual stop arrivals, and a missing prediction stays unknown. A vehicle marker or an added trip in Trip times does not mean Route can use that trip; routing has its own admission rules.

Investigate a condition

1. Start with coverage. Check the assessment time, service window, and reporting coverage in Network. Coverage weights scheduled vehicle-minutes with usable predictions or cancellation reports; it is not the share of passengers covered or service running on time.
2. Follow the route. Open Routes, select the route, and inspect Trip times on the relevant date. Use Stops to confirm direction and pattern, then Updates for service evidence.
3. Inspect the same event. Open the station board or select a vehicle in Line view. Compare arrival with arrival, or departure with departure, at the same stop, keeping both observation times visible.
4. Keep the observation attached. Export observations or Export report retains the current evidence, and Export evidence in the service briefing saves its assessment and source checks.

For a journey, use Route and read its Result and diagnostics. The service assessment method defines the reporting denominator and spacing comparisons.

See what needs attention

Network shows reporting coverage, route comparisons, and the network briefing. A scheduled departure, a feed prediction, and an observed vehicle location are different evidence, and missing reports remain unknown. Overnight service is assessed against the timetable's active window.

With a connected model, the briefing can interpret a pattern, propose an explanation, and suggest a next check. Hypotheses are not confirmed incidents. The briefing checks extracted route-condition claims against computed evidence and performs a model review, but neither guarantees that all prose is correct; a computed fallback is labeled separately.

Inspect a route or station

Open Routes and choose a route to see Trip times; select a trip and date to compare scheduled and predicted arrivals or departures. Stops opens directions and patterns, and Updates opens service evidence. The map and Line view show the same route. Select a stop for its arrivals board, and All routes returns to the catalog. Route and station selection is shared across Network, Routes, the map, and the line view; Network map clears both.

Patterns and scheduled playback

A route's Stops view shows directions, patterns, ordered stops, service span, and published geometry. Patterns are labeled by first and last stops, and Full service restores them all. Direction IDs 0 and 1 are feed labels, not compass directions. Technical IDs appear under Source data. Times such as 25:10 stay on their GTFS service day.

Scheduled playback is labeled Estimated: vehicles dwell at stops and follow their pattern's shape between timed calls. The index does not keep shape_dist_traveled or every untimed call, so interpolated positions are not exact. Live positions stay separate from playback, and route-colored vehicle circles show a bearing arrow when available.

Vehicle timing and line view

In Network → Routes, select a route and choose Line view. The two tracks show each direction's stops and reported vehicles. Select a vehicle on the map or the line to compare scheduled and predicted arrival and departure at its reported stop. If that stop has no usable timing, its prediction stays unavailable; Next prediction names a later stop with one without substituting its time.

Vehicle timing comes from the City's connection store and the current realtime snapshot. The browser requests only the selected route or vehicle every ten seconds, without overlapping requests.

• Stop placement follows the VehiclePosition stop ID, sequence, and status; it never uses road snapping or interpolated movement. Missing or conflicting identities stay unplaced.
• Arrival comes from the incoming connection and departure from the outgoing one, and delay compares the same event at the same stop.
• Opposite directions share a central station list only when their station sequences are exact reverses. Bus stops on opposite sides of a street are not paired by proximity or name.
• Branches and repeated stops stay distinct. Skipped stops, missing predictions, duplicates, and stale observations never become valid current timing.

Spacing is schematic: it shows stop order, not distance, time, or headway. The ↔ warning marks both vehicles in a compressed departure pair, comparing their predictions at the same stop against their scheduled interval.

Added service

Trips declared by GTFS-RT ADDED or NEW appear in the line view and the Trip times selector even when absent from the static timetable. Their reported stop sequences supply placement and timing; partial sequences are labeled as reported stops, and scheduled times and delay comparisons are unavailable. Added-service display does not make a trip available to journey routing; see realtime limits.

Verification and references

test/check-agency-route-line.mjs and test/check-added-service-display.mjs run with npm run check:agency. They cover both directions, branches, repeated and terminal stops, conflicting sequences, stale and future positions, skipped and no-data predictions, and added trips; they verify fixture behavior, not field accuracy. The interaction design drew on TransitMatters Train Tracker and Swiftly's Live Operations overview; no implementation or assets were copied. Matching follows the GTFS Realtime reference.

Connect a model

Open Network → Service briefing → Connect AI, choose a provider, enter its API base URL, choose or discover a model, and connect. The connection test checks function calling, not answer quality. Local models can use a keyless endpoint if their server allows it, and API keys stay in server memory for the session. Briefing requests include the computed assessment and selected source checks; the briefing does not search the web. A localhost URL does not prove where inference runs or whether data is retained.

What this app does not establish

Predicted spacing is not measured headway, and retained forecast changes are not actual vehicle progression. Reporting coverage is not service health. The briefing has no crew roster, maintenance clearance, demand model, or intervention simulator, and rider drafts require staff review; VIGO does not dispatch or publish messages. The operations ledger and synthetic replay are research interfaces.

VIGO 0.5.2 · CLI and HTTP reference · Prepared City format 1

VIGO runs routing and isochrone queries from a single Rust executable. The executable contains the routing kernels, City loader, JSON interface, and HTTP server. It needs no Node, Python, browser, external routing service, or internet connection at query time. SQLite is compiled in. City data is supplied separately and opened read-only.

This manual describes the standalone Rust interface. Requests retain vigo.standalone.query.v1; public results share vigo.route.v1, vigo.matrix.v1, and vigo.reach.v1 with the Node CLI. Studio and the private Python worker protocol remain separate. Run vigo capabilities to identify the executable before integrating it.

• Command lineCommands, flags, files, and standard input.
• Requests and fieldsPoints, clocks, units, and the fields every query shares.
• RouteJourneys, alternatives, via points, and departure windows.
• MatrixTravel times for many origins and destinations in one request.
• ReachRasters, polygons, contours, and street evidence.
• HTTP APIEndpoints, limits, status codes, and authentication.
• Output and errorsPublic results, trace output, and diagnostics.
• Native operationsPacked-array kernel calls and their field reference.

This manual is also part of the searchable, offline VIGO guide, which the engine serves at /. The OpenAPI specification contains the HTTP request contracts and native input/output types. The audit record describes tested coverage and remaining boundaries.

Use the command line to inspect a City, run a query, or start a service.

Commands

All paths are local filesystem paths. Every data command requires --city DIR or VIGO_CITY; this includes compare. Help, version, and capabilities need no City.

Use vigo route --help for the general command overview. --name value and --name=value both work. Unknown options, irrelevant options, repeated options, and extra positional arguments fail. Boolean flags are bare for true or use --pretty=false; --pretty false is not the boolean syntax. The internal _worker command is reserved for the HTTP supervisor.

Query flags

Server flags are listed in the HTTP API reference. Other controls, including transfer buffers, realtime, scenarios, via points, and journey geometry, belong in JSON. CLI query flags override fields from the request file. Stream flags override every line, so omit a stream-level service date when sending different dates.

Files and standard input

Input files/stdin accept one JSON object and an optional UTF-8 BOM, up to 8 MiB. A request read from stdin completes when stdin closes. JSON goes to stdout; logs/errors go to stderr. With a file output, the result is saved instead of printed. Writes are staged and renamed atomically, preserving an existing file's permissions. The output directory must already exist. No CSV batch interface is provided; use Matrix or Stream.

The compiler, vigo-build, builds Cities and runs Route, Matrix, Reach, Stream, and Compare through VIGO's shared native routing kernel. The engine has its own command set; see the engine CLI reference.

Commands

Run vigo-build help route or vigo-build route -h for options, and vigo-build --version for the version. Unknown options, extra positional arguments, and repeated single-value options are rejected; --gtfs, --gtfs-scope, and --prepare-date may repeat.

Send a request

Requests carry serviceDate and time in JSON, and flags override request fields exactly as in the engine:

vigo-build route --city ./boston --request route.json --output route-result.json
cat route.json | vigo-build route --city ./boston --request - --time 08:30 > route-result.json

Request files and stdin share a 16 MiB limit, and --request - reads until the producer closes stdin. Progress and errors go to stderr; JSON goes to stdout. Saved output is staged and renamed after a complete write, so a failed run can leave an earlier output file in place: check the exit code. CSV Route batches use --input with an output file, support transit only, and cannot be combined with --request.

Keep the compiler resident

stream reads one request per line, each with an explicit kind, and keeps prepared network state between lines. Each line may choose its own serviceDate; a --service-date flag only sets the default.

{"id":"outbound","kind":"route","origin":{"stopId":"A"},"destination":{"stopId":"B"},"serviceDate":"2026-10-05","time":"08:00"}
{"id":"times","kind":"matrix","origins":[{"stopId":"A"}],"destinations":[{"stopId":"B"}],"serviceDate":"2026-10-05","time":"08:00"}

vigo-build stream --city ./city < queries.ndjson > results.ndjson

Responses echo id and add sequence. A per-line error does not end the stream. First-use preparation, later queries, and serialization are different timing boundaries.

Read a response

Public Results identify schema, status, and query metadata: Route uses journey, Matrix durationsSeconds, and Reach surface.valuesSeconds or map-only areas, all in seconds. diagnostics: "trace" adds internal evidence under trace; applications should use the public result reference. An invalid one-shot request exits nonzero, and stream errors use schema: "vigo.error.v1" with error.code and error.message.

VIGO Python runs the same resident protocol with its own Result properties. Studio's internal application API is not a public integration boundary.

Queries accept map coordinates or stop IDs. Transit queries also need a service date and a clock time.

Coordinates and stop IDs

Use [longitude, latitude] in WGS84 decimal degrees. Longitude must be −180…180, latitude −90…90. Kilometers are used for high-level walking/street limits; output geometry distances are meters; high-level times are minutes. Native operations use seconds/meters unless a field explicitly names another unit.

{"coordinate": [-77.05, 38.9]}

{"stopId": "A"}

A point may also be a bare coordinate array. Point objects accept id, name, label, source, and scenario metadata editStatus, baselineStopId, baselineStopIndex. These labels do not change routing. A valid stopId takes precedence over a coordinate, except source: "map", which deliberately uses the coordinate. Selected stations/platforms include their prepared station members. This selection does not certify a physical path between every platform.

Exact identifiers are case-sensitive. Multi-feed IDs may contain a feed scope and the JSON separator \u001f. Obtain active IDs with timetable.identifiers; do not assume a local ID is unique in a combined City.

Common query fields

Service time and walking policy

Transit times are service-day clocks, including after-midnight GTFS hours. Calendar queries include services on adjacent dates when their trips overlap the search interval. GTFS clocks use local noon minus twelve elapsed hours, including daylight-saving changes. journey.clockDate anchors every journey and leg clock; a transit leg's serviceDate identifies its actual operating date, and hours can exceed 23. Street-only queries still require a clock but can omit serviceDate.

The depart-at timetable search ends at departure plus horizon; arrive-by searches back to the later of midnight and arrival minus horizon. A transit egress walk may extend beyond the depart-at scan horizon. Direct walking is bounded by physical walking duration as well as its distance cap. Drive routing uses its street-distance limit and supplied static metric; horizonMinutes does not add a drive travel-time cutoff.

City access padding/overhead apply to boarding access, not physical direct-walk duration. The transfer buffer applies once after walking and source-defined transfer minima; it does not delay first boarding, final egress, or staying aboard. allowStreetTransfers: false retains endpoint access and egress. Neither control establishes station accessibility or fare-transfer eligibility.

arrivalBufferMinutes is an optional integer 0–60 (default 0) for arrive-by Transit Route and Matrix. A positive value reserves time before the final deadline while retaining the original earliest departure. The deadline must be at least the reserve, and horizonMinutes must exceed it by at least one minute. Positive reserves reject via points, depart-at, Walk, Drive, Reach, and native operations. diagnostics.timeReserves records both deadlines and calibratedProbability: false. Route and journey clocks retain their actual modeled times; Matrix scalar durations include the reserve. Combine with minimumTransferBufferMinutes for time at intermediate changes. See Travel-time uncertainty for the Boston example and calibration requirements; a margin is not a probability guarantee.

Route finds a journey between an origin and a destination at a chosen time. Transit queries also require a service date. A valid query with no journey returns status: "not_found".

Reference fixture

The remaining reference examples use the small public test network A → X → B, with service on 2026-07-15. It is also used by the localhost demonstration on port 8787. These IDs do not belong to Boston; use the coordinates and data above for your own first queries.

A depart-at request requiring transit, so the fixture illustrates ride and transfer clocks:

{
  "origin": {"stopId": "A"},
  "destination": {"stopId": "B"},
  "serviceDate": "2026-07-15",
  "time": "07:55",
  "maxWalkKm": 0.2,
  "requireTransitRide": true
}

Its response excerpt (legs, metadata, and diagnostics omitted):

{
  "schema": "vigo.route.v1",
  "status": "ok",
  "mode": "transit",
  "journey": {
    "departureTime": "07:55:00",
    "arrivalTime": "08:30:00",
    "durationSeconds": 2100,
    "transfers": 1,
    "walkingSeconds": 0,
    "ridingSeconds": 1500,
    "waitingSeconds": 600
  }
}

The journey departs at 07:55 and arrives at 08:30, with 25 minutes riding and 10 minutes waiting. transfers: 1 means two boardings. Public journey durations are integer seconds, and journey clocks are local service-day HH:MM:SS. See Results and errors for the full response structure.

Transit

An arrive-by request for the fixture:

{
  "origin": {"stopId": "A"},
  "destination": {"stopId": "B"},
  "serviceDate": "2026-07-15",
  "time": "08:30",
  "timePreference": "arrive_by",
  "maxWalkKm": 0.2,
  "maxTransfers": 1,
  "requireTransitRide": true,
  "allowStreetTransfers": false,
  "minimumTransferBufferMinutes": 5
}

Walking and driving

For a walk query, specify coordinates, walking speed, and a street-distance limit:

{
  "origin": {"coordinate": [-77.05, 38.9]},
  "destination": {"coordinate": [-77.03, 38.91]},
  "time": "07:55",
  "mode": "walk",
  "walkSpeedKph": 4.8,
  "maxStreetKm": 5
}

Change mode to drive and remove walkSpeedKph for a drive query. Street paths follow directed OSM routing, including snap diagnostics; drive geometry uses its routed node sequence.

Direct walking policy

For transit coordinate requests, a direct OSM walk competes with transit by default. Set requireTransitRide: true to require a vehicle boarding. A blocked request containing an explicitly selected stop does not gain a direct-walk fallback. A ready selected-stop route can still be replaced by a winning direct walk when that policy is false. Set mode: "walk" when walking is the intended operation.

Journey geometry

Route includes its materialized leg geometry by default. Set includeGeometry: false to omit coordinate arrays from the public response. Matrix geometry remains opt-in. A transit leg's line runs from the boarding stop through the aligned source-shape vertices to the alighting stop; distanceMeters is the length of that line. Missing source shapes fall back to a labeled stop sequence. Transit legs carry GTFS fare annotations when the City publishes fares. Studio's balanced/preference presentation is not part of this interface.

Ask for several journeys at one time, plan through intermediate points, or compare departures over a time window.

Alternative journeys

alternatives (0–9, default 0) asks a depart-at transit Route for additional transit journeys at the requested time. The primary journey stays in journey; the others appear in alternatives, earliest arrival first. Both runtimes return the same alternatives for the same request.

alternativeRanking chooses them:

• pareto (default) keeps only trade-offs: an alternative must beat every other returned journey on arrival, boardings, or walking. It uses no more boardings than the primary journey. When more trade-offs exist than requested, the fewest boardings and the least walking are kept first.
• ranked keeps the earliest arrivals even when another journey is better in every respect, then prefers fewer boardings and less walking. It admits one more boarding than the primary journey, within maxTransfers. Journeys on the same sequence of vehicles count once, whatever stops they use to change or leave.

alternativeSlackMinutes (0–120, default 15) bounds how much later than the primary journey an alternative may arrive. alternativeSearch records coverage: "requested_time", ranking, maximumJourneys (including the primary), arrivalSlackMinutes, and status. A search that exceeds the kernel's label budget reports status: "unavailable" with a reason and returns the primary journey alone. Alternatives are transit journeys; a faster direct walk remains the primary journey. Requests that combine alternatives with arrive-by, via points, or a journey window are rejected.

{
  "origin": {"stopId": "A"},
  "destination": {"stopId": "B"},
  "serviceDate": "2026-07-15",
  "time": "07:50",
  "alternatives": 3,
  "alternativeRanking": "ranked",
  "maxWalkKm": 0.2,
  "requireTransitRide": true
}

Via points

Supply via (alias waypoints) as an ordered array of at most 16 points. Do not supply both aliases. Each segment is routed in order, carrying time forward for depart-at or backward for arrive-by. Results contain segments, not one flattened journey. A blocked segment reports reason: "via_leg_blocked" and legIndex.

{
  "origin": {"stopId": "A"},
  "destination": {"stopId": "B"},
  "via": [{"stopId": "X"}],
  "serviceDate": "2026-07-15",
  "time": "07:55",
  "maxWalkKm": 0.2
}

Transit via requests require a boarding on every segment. They reject an explicit maxTransfers or a nonzero transfer buffer because independent segment composition cannot certify the transfer boundary. No dwell/visit duration is added at a via point.

Journey windows

windowMinutes accepts 0–240 (default 0). A positive value samples searches at windowStepMinutes intervals (1–60, default 1), including the requested time. Depart-at searches move toward later departures; arrive-by searches move toward earlier arrival deadlines. Results retain up to five distinct, nondominated journeys, sorted by earliest arrival for depart-at or latest departure for arrive-by, then fewer boardings and less walking. The primary journey is in journey, with the remaining choices in alternatives.

alternativeSearch records minutes, stepMinutes, searches, and direction (later_departures or earlier_arrival_deadlines). Transit alternatives at each sample use a 15-minute slack; the direct-walking comparison can lie outside that envelope. This is a sampled search, not a continuous all-departures guarantee. A nonempty via list takes precedence and removes window sampling from its segments; do not combine the two when you need window alternatives.

These fields are supported by the standalone Rust CLI and its HTTP service. The Node CLI instead supports --departure-window or JSON departureWindowMinutes for a centered depart-at profile of ±0–30 minutes. It rejects the standalone window fields, and rejects positive centered profiles with arrive-by, rather than silently running a point query.

{
  "origin": {"stopId": "A"},
  "destination": {"stopId": "B"},
  "serviceDate": "2026-07-15",
  "time": "07:50",
  "windowMinutes": 15,
  "windowStepMinutes": 1,
  "maxWalkKm": 0.2,
  "requireTransitRide": true
}

Matrix calculates travel times between every origin and destination in a request. It supports transit, walking, and driving.

Build a matrix

Supply origins and destinations arrays with at least one point each. Use point objects or coordinate pairs as entries. A request can contain up to 65,536 origin–destination pairs. Row order follows origins; column order follows destinations.

{
  "origins": [{"stopId": "A"}, {"stopId": "X"}],
  "destinations": [{"stopId": "B"}, {"stopId": "A"}],
  "serviceDate": "2026-07-15",
  "time": "07:55",
  "maxWalkKm": 0.2,
  "requireTransitRide": true,
  "includeJourneys": true,
  "includeGeometry": true
}

Read the matrix

durationsSeconds[row][column] gives seconds from the shared departure to arrival for depart-at, or from the latest departure to the shared deadline for arrive-by. In the latter case, it can exceed the accompanying journey's duration when the journey arrives before the deadline. JSON null means unreachable. See Matrix output for indexing, examples, and journey details.

Include journeys

includeJourneys defaults to false and is supported for transit only. With true, journeys has the same dimensions and nulls for unreachable pairs. includeGeometry defaults to false and requires journeys. When direct walking wins, its journey contains a timed walking leg, with geometry if requested. Large journey/geometry matrices can reach the HTTP response limit; split them into smaller requests.

journeyFormat defaults to "full", retaining stop names, route details, stop sequences, and walking evidence. Analytical callers can explicitly request "compact" with includeJourneys: true: it returns the same selected trips, stops, boarding sequences, leg clocks, transfers, and walking/riding/waiting durations without display metadata or walking-evidence annotations. Compact does not accept includeGeometry: true. For duration-only workloads, leave includeJourneys false. Compare performance at the same output detail; the Node Matrix interface returns compact witnesses.

Repeated endpoints

Transit Matrix keeps repeated endpoints grouped through transit search, direct walking and journey geometry, then expands completed answers into the requested row and column order. Exact-stop and coordinate endpoints retain their respective routing semantics. Trace diagnostics expose matrixReuse.requestedPairs, searchPairs, uniqueOrigins and uniqueDestinations. The 65,536-pair response limit still applies; this reuse does not approximate or merge distinct endpoints.

Run node scripts/benchmark-service-reuse.mjs --reference /path/to/baseline-vigo --samples 31 --output comparison.json to compare two executables on a generated public fixture. The check compares complete answers and reports date preparation, retained-date switches, repeated and distinct Matrix pairs. Engine execution time and the detailed-output round trip are recorded separately. This small fixture tests reuse and regressions; metropolitan scaling needs a separate workload.

Reach finds the streets and areas accessible from an origin within a set of travel-time limits. Transit queries combine timetable travel with walking over the prepared street network. Use mode: "walk" for walking only, or call isochrone as an alias of reach.

Reach supports depart-at queries. Drive and realtime transit are unavailable in Reach; see Compatibility for the supported combinations.

Request

{
  "origin": {"stopId": "A"},
  "serviceDate": "2026-07-15",
  "time": "07:55",
  "cutoffsMinutes": [15, 30, 45],
  "maxWalkKm": 0.5,
  "walkSpeedKph": 4.8,
  "extentRadiusKm": 2,
  "rasterSize": 48,
  "includeStreetEdges": true
}

Options

Do not supply horizonMinutes, maxStreetKm, requireTransitRide, or allowLongWalk to Reach. The largest cutoff bounds the analysis. Walk-only Reach accepts a clock without a service date and cannot apply a transit scenario.

Cell-center sampling uses the Matrix walking allowance and fixed requested bounds. It supports walking or scheduled transit, without planned service changes. Transit uses the City's prepared 4.8 km/h walking policy; other speeds are rejected. Street sampling supports planned service changes and adjustable walking speed.

Read the surface

surface.valuesSeconds is a flat row-major array of elapsed seconds starting at the northwest corner. For width w, cell index is y*w+x. Null means no finite value was retained; numeric zero is valid. Given bounds [west,south,east,north], cell centers are:

longitude = west + (x + 0.5) / width  * (east - west)
latitude  = north - (y + 0.5) / height * (north - south)

fullSurface.valuesSeconds uses fullSurface.bounds and the same dimensions, with bounds recomputed from reached street evidence when available. Those bounds can be smaller or larger than the requested view. Never interpret full values using the requested bounds. areas/fullAreas are GeoJSON FeatureCollections of MultiPolygons; contours/fullContours contain MultiLineStrings. Features carry cutoffMinutes. Areas preserve holes and disconnected components; isolines interpolate the raster rather than inventing a convex hull through unreachable space. Raster resolution affects presentation and area estimates. See Reach output for decoding and interpretation.

Map output

For map display, Reach accepts reachFormat: "map". It returns the full reached-area polygons as areas, their bounds, and the usual query metadata, without stop lists, duplicate contour representations or raster values. The polygons match fullAreas from reachFormat: "full", which remains the default for analysis and raster comparisons. Output selection does not change the search.

Street evidence

Street evidence is surface.edges with schema vigo.standalone.street-edges.v2, encoding indexed-json. It retains partial directed intervals, with coordinates and times decoded as shown under Reach output. This encoding differs from Studio's binary edge bundles.

Test service changes by applying a scenario to a Reach query. Each scenario lasts for that request; it leaves the City and later requests unchanged.

A scenario object accepts id, name, optional matching cityRevision, excludedTripIds, excludedRouteIds, services, or overlay. Use exact active City identifiers. An exclusion only affects matching scheduled trips.

A supplied cityRevision must match the loaded City. Choose either nonempty services or overlay. Editor-only IDs/fields are rejected; hydrate branch edits into explicit schedules before using this interface.

Frequency service

{
  "origin": {"stopId": "A"},
  "serviceDate": "2026-07-15",
  "time": "07:55",
  "cutoffsMinutes": [15, 30, 45],
  "extentRadiusKm": 2,
  "rasterSize": 48,
  "maxWalkKm": 0.2,
  "scenario": {
    "services": [{
      "id": "express",
      "operation": "add",
      "scheduleMode": "frequency",
      "stops": [{"stopId": "A"}, {"stopId": "B"}],
      "bidirectional": false,
      "startMinutes": 475,
      "endMinutes": 600,
      "headwayMinutes": 5,
      "timeModel": "preserve-scheduled",
      "segmentRuntimeMinutes": [5]
    }]
  }
}

At most 128 services and one million planned stop events are accepted. The default estimate-distance model uses projected stop distance, speed, and dwell; merely supplying runtime arrays does not select them. preserve-scheduled uses supplied runtimes, falling back to distance estimates where no runtime array exists. infer-road consumes supplied distances/runtimes; the standalone service does not infer them from a road route. Use a documented preparation method for those inputs.

augment retains existing service. Frequency replacement uses operation: "replace", scheduleMode: "frequency", and sourceRouteId; matching active trips are removed. If scheduledTrips is provided on a replacement service, its original trip IDs define the removal set. Added service can operate on a date with no active baseline service.

Preserve explicit departures and dwell

{
  "origin": {"stopId": "A"},
  "serviceDate": "2026-07-15",
  "time": "07:55",
  "cutoffsMinutes": [30, 45],
  "extentRadiusKm": 2,
  "rasterSize": 48,
  "maxWalkKm": 0.2,
  "scenario": {
    "services": [{
      "operation": "replace",
      "scheduleMode": "preserve-trips",
      "stops": [{"stopId": "X"}, {"stopId": "B"}],
      "scheduledTrips": [{
        "tripId": "T2",
        "departureSeconds": 29700,
        "arrivalOffsetsSeconds": [0, 600],
        "departureOffsetsSeconds": [0, 600],
        "canBoard": [1, 0],
        "canAlight": [0, 1]
      }]
    }]
  }
}

Offsets are seconds relative to that run's departureSeconds; every array matches the stop count. Permissions are zero/one; omitted permission arrays default to all allowed. Times must preserve chronological arrivals/departures. Replacement tripId must be active. Preserve-trips mode does not manufacture reverse runs or automatically recover the original timetable.

Compiled overlays

Advanced clients can supply scenario.overlay: stops, overlayStopCount, direction offsets/stops/times, service windows/headways, and supplemental transfer arrays from TimetableOverlayManyQueryInput. The stop count must equal the coordinate-bearing stop list and be at most 256. The adapter creates endpoint seeds and destinations; the overlay cannot override those base query fields. Direction stop indices use the overlay-local domain; supplemental transfers use the combined resident-plus-overlay domain. Use the native reference for the exact array types and offset conventions.

Compare two Reach results on the same grid to find where travel times improve, worsen, or become unavailable.

Prepare the comparison

Save baseline and scenario Reach responses, then construct a JSON object with those complete objects under before and after. Do not pass filenames as the two values.

python3 - <<'PY'
import json
with open('baseline.json') as f:
    before = json.load(f)
with open('scenario.json') as f:
    after = json.load(f)
with open('comparison.json', 'w') as f:
    json.dump({'before': before, 'after': after}, f)
PY
./vigo compare --city ./city --request comparison.json --output change.json

Python here is an optional client utility. The Rust command still requires a City path in this version, even though comparison itself uses saved grids. Both results must declare the same nonempty City revision, bounds, dimensions, and compatible numeric/null raster arrays. Compare does not rerun routing and does not currently compare Route or Matrix results.

Interpret changes

The public result, vigo.compare.v1, reports changes after minus before. counts splits the comparable cells, reachable in both, into faster, slower, and unchanged, and counts newlyReachable and noLongerReachable cells separately. meanChangeSeconds averages comparable cells only, is negative when travel got faster, and is null when no cell is comparable. Request diagnostics: "trace" for the per-cell deltaMinutes grid described in Comparison output; a null delta is not a zero change.

Hold origin, clock/date, walking policy, cutoffs, and grid fixed when interpreting a scenario effect. The comparator does not certify all those experiment settings or compare City revisions.

Supply transit predictions or traffic observations with a query to use them in routing. Your application is responsible for fetching and decoding the source feed.

Each query uses only the snapshot supplied with it. Omission restores scheduled/baseline routing on the next request. Explicit routingDataMode: "scheduled" rejects observation input; "realtime" requires a snapshot or traffic. Without an explicit mode, supplied input selects its corresponding observation path.

Transit snapshot

Transit realtime supports Route only. Use a FULL_DATASET snapshot with tripUpdates. Feed timestamps are Unix seconds, not milliseconds. A record needs sourceFeedTimestamp or the enclosing feedTimestamp, no older than 180 seconds and at most 60 seconds in the future. If present, its own timestamp must also be fresh.

Create a current synthetic delayed-trip request from route.json:

python3 - <<'PY'
import json, time
with open('route.json') as f:
    query = json.load(f)
query['routingDataMode'] = 'realtime'
query['realtimeSnapshot'] = {
    'incrementality': 'FULL_DATASET',
    'feedTimestamp': int(time.time()),
    'tripUpdates': [{'tripId': 'T2', 'delaySeconds': 600}]
}
with open('realtime-route.json', 'w') as f:
    json.dump(query, f)
PY
./vigo route --city ./city --request realtime-route.json

For real use, preserve the source's timestamp; do not replace stale provider time with the current clock. The example refreshes time only to make a synthetic test record.

A stop update uses integer stopSequence or an unambiguous stopId; both, if present, must agree. Loop calls need a sequence. arrival and departure are separate objects containing integer delay seconds or absolute time epoch seconds. Absolute timestamps require realtimeSnapshot.timezone (IANA name) when the City has no single timezone. SKIPPED removes a call; NO_DATA resets propagated delay. Terminal sequence inference is limited to an identified terminal stop; unknown intermediate calls are not guessed.

Invalid, duplicate, stale, ambiguous, or mismatched records preserve scheduled service and increment diagnostics. A malformed enclosing snapshot fails the request. Omitted past prefixes can be removed only when source clocks establish that the omitted calls are past; their boarding opportunities are removed with them. Cached snapshot validity changes at freshness/source-clock boundaries.

Read diagnostics.realtime for coverage and the numbers of applied, canceled, stale, invalid, duplicate, and unmatched records. A successful route may use scheduled fallback. A fresh prediction is not a verified arrival or a completeness guarantee.

Drive traffic

Drive Route and Matrix accept traffic.observations (aliases segments, edgeUpdates). Supply observedAt (aliases fetchedAt, timestamp), optional ttlSeconds (default 300; range 1–1800), and optional expiresAt. Traffic timestamps accept RFC3339 or numeric Unix seconds/milliseconds. Expired data or observation time more than 60 seconds in the future is rejected.

Each observation identifies directed coordinates (2–512 points), fromCoordinate/toCoordinate, or fingerprint-bound edgeIndices. Choose exactly one effect:

At most 100,000 observations and 200,000 affected edges are accepted. Geometry is matched to the prepared drive graph. Opposite directions are separate. Overlapping observations retain the largest cost; the adapter does not reduce an edge below baseline travel time. This is one supplied static metric snapshot, not time-varying congestion prediction during the trip.

Raw callers may provide snapshotKey, edgeIndices, and edgeTimeUnits (hundredths of seconds), plus the City drive streetSourceFingerprint in the high-level traffic object. A closed edge has weight 2147483647. Actual weights, not just the caller key, determine cache identity. The raw path does not perform timestamp expiry; its producer must manage observation validity and correct graph identity. Low-level native drive inputs already assume the correct index domain.

Default output is a compact journey or analysis result. See the public result contract for every field, unit, evidence boundary, and migration rule.

• --format text|json selects terminal text or JSON; pipes and saved files use JSON by default.
• --diagnostics none|summary|profile|trace selects optional detail. Default is none.
• Route includes available leg GeoJSON by default; --include-geometry=false omits it. Matrix geometry remains opt-in with --include-geometry. --include-limitations adds dataset limitations.
• HTTP accepts the equivalent body fields or ?diagnostics=summary, ?includeGeometry=true, and ?includeLimitations=true.
• Route uses journey; Matrix uses durationsSeconds; Reach uses surface.valuesSeconds and fullSurface.
• status: "ok" means a result, not_found means no admissible journey, and error means failure.
• meta separates engine version, City revision, request identity, query fingerprint, and measured compute time.

Stream consumers may select --stream-output=detailed after checking that capabilities.output.streamFormats includes detailed. This returns the internal vigo.stream.detail.v1 envelope without constructing the public projection; its trace contains the routing outcome. This format is an unstable wrapper interface. See the public result reference for envelope and error semantics.

The public result contract defines the default output. The rest of this chapter documents the internal trace.

Trace reference (debug only)

The rest of this section documents the internal object under trace, obtained with diagnostics: "trace" or stream --stream-output=detailed. These raw fields are retained for debugging and old research tooling, not the default public schema. All old response excerpts below refer to trace. For native operations the raw result remains the direct response. CLI examples in earlier sections use the clean default; old exact field excerpts are trace excerpts.

Read the outcome first, then the journey or analysis data. Keep units, array ordering, and evidence provenance alongside the values when storing or displaying a result.

Timing and metadata

Successful dispatch of Route, Matrix, Reach, and Native adds these fields. A computed blocked Route also receives them. Error objects use a separate envelope.

The successful response is the result object itself, without a surrounding data property. Native is the exception in structure: its low-level object is inside result, alongside operation. JSON member order has no meaning. Accept additional fields; inspect the requested family before requiring fields that only exist on particular variants.

serviceDate and dataMode are included on transit Route results; they are not universal metadata. Reach echoes serviceDate (null for a walk-only query without one). Matrix does not echo the date, points, or requested clock. Store the request beside the response when you need reproducible interpretation.

Response fields

Computed outcomes and errors

Do not require kind or status on every family. Route has status but does not uniformly carry kind; Matrix, Reach, and Compare have kind and no top-level Route status. Native has operation. HTTP /v1/info returns the startup City summary without per-query timing.

CLI failures exit 2 and write a JSON error on stderr:

{"error":{"code":"invalid_request","message":"serviceDate (YYYY-MM-DD) is required for transit"}}

Public errors use schema: "vigo.error.v1" and status: "error". Transport failures use codes such as unauthorized, request_timeout, query_timeout, and service_unavailable; read the code together with HTTP status. A public not_found Route exits 0 and uses HTTP 200. Stream puts per-line errors on stdout and can continue; errors have no normal result timing or City wrapper. See HTTP status codes for 400, 503, and 504 handling.

A Route result describes one journey, a sequence through via points, or a sampled set of departure choices. Start with status, then select the variant by the presence of segments or choices.

Journey clocks and totals

For the reference fixture route, the following is an exact selection of fields. Legs, diagnostics, and metadata are omitted:

{
  "status": "ready",
  "mode": "transit",
  "departureMinutes": 475,
  "arrivalMinutes": 510,
  "durationMinutes": 35,
  "boardings": 2,
  "transfers": 1,
  "walkMinutes": 0,
  "rideMinutes": 25,
  "waitMinutes": 10
}

Here 475 is 07:55, 510 is 08:30, and 35 = 0 + 25 + 10. Values can be fractional. Service-day clocks can exceed 1440 minutes: 1500 is 25:00 on the selected service day, not a Unix timestamp. Do not apply modulo 24 hours before retaining the date offset.

Read the leg sequence

Geometric walk legs retain the selected access cost. When that cost includes a station connection, accessCost.street and accessCost.station separate their distances and seconds; the station component includes directed stop IDs and source names. A published transfer minimum is timing evidence, not an interior walking-path witness. stationAccessStatus: "unverified" and streetPathVerified: false retain that uncertainty. streetSegmentVerified describes only the street portion. A source-backed pathway can report stationAccessStatus: "source_path". A fallback line between stops is never labelled a verified OSM walk. unverifiedStationAccessLegs counts unresolved station connections in the returned journey.

legs is ordered from origin to destination. The fixture route contains two zero-duration station-selection walk legs around two rides. Waiting is represented by gaps between legs, not separate wait legs:

This excerpt is the first ride, legs[1]. Other properties are omitted:

{
  "kind": "ride",
  "tripId": "T1",
  "routeId": "R1",
  "fromStopId": "A",
  "toStopId": "X",
  "departureMinutes": 480,
  "arrivalMinutes": 490,
  "durationMinutes": 10,
  "stopIds": ["A", "X"],
  "stopCount": 1,
  "geometrySource": "stop_sequence",
  "coordinates": [[-77.05, 38.9], [-77.04, 38.905]]
}

To draw one leg as GeoJSON, use {type: "LineString", coordinates: leg.coordinates} when coordinates are available. Preserve separate legs and their provenance. Zero-length station-selection lines can be hidden in a map without removing their role from the itinerary.

Geometry and evidence

Only transfers certified from OSM follow a street path; a parent-station link keeps its modeled time and a straight line. These labels apply to materialized transit legs. streetPathVerified: true identifies a graph-verified walking leg; false is explicit for the fallback labels. Ride legs and direct Walk/Drive legs do not use that flag in this version. Missing does not mean false. Graph verification does not establish wheelchair access, station-interior access, or fare eligibility.

Route always materializes geometry. Matrix journeys only add coordinates, geometrySource, and geometry-derived distances when includeGeometry is true. This changes detail, not whether the duration cell is reachable.

Direct, via, window, and blocked variants

Direct Walk/Drive results have a single street leg, distanceMeters, clocks, and transfers: 0. They omit transit totals such as boardings and waitMinutes. A transit request with requireTransitRide: false can return mode: "walk"; display the returned mode rather than the requested preference.

Via routes have ordered segments and a top-level duration spanning them. They do not have one flattened legs array or aggregate transfer/walk/ride totals. Segment objects omit the outer dispatch metadata. No visit duration is added at a via point.

Window routes have the selected journey at the top level and up to five retained alternatives in choices, ordered by arrival. window.searches counts sampled departure times, including unsuccessful and deduplicated searches; it is not the number of choices. Retained choices are not a continuous enumeration of every departure.

Reversing A → B to B → A in the fixture route produces this exact field selection:

{"status": "blocked", "mode": "transit", "reason": "no_path"}

no_access means one endpoint has no admissible transit candidates; no_path means no path was found under the query. Direct street arrive-by can return before_service_day if it would require a negative departure clock. Drive may return its native reason. A failed via route returns via_leg_blocked, a zero-based legIndex, and the blocked segment under leg. Do not read duration or geometry without a ready outcome.

A Matrix result is indexed by the request's origins and destinations. Keep those arrays with the result: the response includes counts but does not repeat their labels or coordinates.

Rows, columns, and nulls

The Matrix request uses origins [A, X] and destinations [B, A]. Its exact summary is:

{
  "kind": "matrix",
  "mode": "transit",
  "originCount": 2,
  "destinationCount": 2,
  "durationsMinutes": [[35, null], [35, null]]
}

durationsMinutes[1][0] is X → B. Starting at X at 07:55 includes 20 minutes waiting and 15 minutes riding. The A → A cell is null because this transit query requires a ride and the fixture has no returning service. Do not fill the diagonal with zero by assumption.

Rows follow origins and columns follow destinations even for arrive-by. No symmetry is implied. null is an unavailable pair under these inputs, while numeric zero is a valid zero duration. Avoid truthiness checks such as if (duration); use duration !== null and retain the count of excluded pairs when aggregating.

Depart-at and arrive-by durations

For transit, the high-level matrix converts native clocks as follows:

depart-at: duration = (arrival clock - requested departure clock) / 60
arrive-by: duration = (requested deadline - latest departure clock) / 60

The clocks in these formulas are seconds. With A → B and an 08:40 arrive-by deadline, the result cell is 40 minutes: latest departure 08:00 to deadline 08:40. The included journey actually arrives at 08:30 and has 30 minutes of elapsed journey time. Both values are intentional. The extra ten minutes are slack before the deadline, not another ride or a waitMinutes entry in the journey.

Walk/Drive matrices use their street travel durations. distancesMeters is a second two-dimensional array in the identical order. Transit matrices omit this distance array.

Journey detail

Materialized transit journey cells have the Route journey fields, but no outer status, mode, or dispatch metadata. Read reachability from the duration cell and null journey entry. Do not parse every cell as a complete Route response.

diagnostics.times remains the native flat array of clocks in seconds. For the same cell, its native offset is row * destinationCount + column. It is not interchangeable with the high-level duration matrix, especially when a direct walk replaces a transit result.

High-level Route and Matrix diagnostics retain native clocks and search counters but set the nested native journeys to null. The complete materialized journeys are returned once in the high-level result. Use the explicit native operation timetable.matrix when raw native journey records are required.

Reach returns transit stop arrivals, a raster, area/contour GeoJSON, and optional street evidence. surface.sampling distinguishes reached street samples from routes to grid centers.

Main fields

Stop durations are elapsed minutes from the query clock. They are not clock minutes or final egress times. Stop order follows the active timetable/planned-stop order, not increasing duration. Sort explicitly for a ranked list. Transit stops and raster cells need not have one-to-one coverage because the raster also depends on the prepared street graph.

Decode the raster

surface.width * surface.height equals surface.values.length. Index zero is at the northwest. X grows east and Y grows south. In street sampling, each finite value is the least elapsed time retained from sampled reached street intervals. In cell-center sampling, it is the Matrix travel time to the cell center. Neither promises a path to every point in the cell. Null means no finite value was retained under the query limits.

This client function reads a cell without confusing zero with null:

function readCell(surface, x, y) {
  const { width, height, bounds, values } = surface;
  if (!Number.isInteger(x) || !Number.isInteger(y) ||
      x < 0 || x >= width || y < 0 || y >= height) {
    throw new RangeError('Cell is outside the raster');
  }
  const [west, south, east, north] = bounds;
  return {
    index: y * width + x,
    coordinate: [
      west + (x + 0.5) / width * (east - west),
      north - (y + 0.5) / height * (north - south)
    ],
    durationMinutes: values[y * width + x]
  };
}

The coordinate is the cell center: a display location for street sampling and the queried destination for cell-center sampling. A cell belongs to a cutoff when its value is not null and is at most that cutoff. Keep the original floating-point value for analysis; round only for display.

For the full raster, pass {...surface, bounds: surface.fullBounds, values: surface.fullValues}. The full pair always exists in the high-level output; it falls back to the requested pair when no separate surface is produced. Both use the same dimensions. Recomputed bounds can be smaller or larger, so equal array indices need not refer to the same place. Changing bounds at fixed dimensions also changes cell size.

Areas and contours

Each collection has type: "FeatureCollection" and a features array. Each feature has properties.cutoffMinutes and one of these geometries:

Area thresholds are cumulative, not disjoint bands. A 30-minute feature includes cells also reachable in 15 minutes; do not add their areas together. A cutoff with no generated geometry has no feature, so match features by cutoffMinutes, not by array position. An empty collection is valid.

Areas trace occupied raster cells; contours interpolate threshold crossings. They can differ along boundaries. Both are resolution-dependent representations, not surveyed travel boundaries. Reproject or use geodesic methods for area measurements rather than treating longitude/latitude degrees as meters. Preserve holes and disconnected components when rendering.

Decode directed street evidence

With includeStreetEdges: true, surface.edges uses schemaVersion: "vigo.standalone.street-edges.v2" and encoding: "indexed-json". Without it, edges is null. An included but empty bundle has count zero and empty arrays.

All measurement arrays have length count. Repeated edge IDs describe ordered, non-overlapping intervals; opposite directions are separate records. Interpolate coordinates between the referenced graph vertices using the interval fractions. For a smaller cutoff, clip an interval between its start and end times instead of dropping the whole interval.

function readEdge(bundle, i, cutoffMinutes = Infinity) {
  if (!Number.isInteger(i) || i < 0 || i >= bundle.count) {
    throw new RangeError('Edge is outside the bundle');
  }
  const point = node => bundle.nodes.slice(2 * node, 2 * node + 2);
  const from = point(bundle.endpoints[2 * i]);
  const to = point(bundle.endpoints[2 * i + 1]);
  const start = bundle.startFractions?.[i] ?? 0;
  const end = bundle.endFractions?.[i] ?? 1;
  const startTime = bundle.fromDurationMinutes?.[i] ?? bundle.durationMinutes[i];
  const endTime = bundle.durationMinutes[i];
  if (cutoffMinutes < startTime) return null;
  const clippedEnd = endTime <= cutoffMinutes ? end
    : start + (end - start) * (cutoffMinutes - startTime) / (endTime - startTime);
  if (clippedEnd <= start) return null;
  const coordinate = fraction => from.map((v, axis) => v + fraction * (to[axis] - v));
  const seed = bundle.transitArrivalMinutes[i];
  return {
    edgeId: bundle.edgeIds[i],
    coordinates: [coordinate(start), coordinate(clippedEnd)],
    durationMinutes: Math.min(endTime, cutoffMinutes),
    walkDistanceM: bundle.walkDistanceM[i],
    transitArrivalMinutes: seed === -1 ? null : seed
  };
}

Here the client deliberately converts the -1 sentinel to null for display. The API array still contains -1. Retain edgeIds when comparing bundles from the same graph; local endpoints indices can change from one bundle to another. Check diagnostics.surface.edgeEvidenceTruncated before treating the records as exhaustive.

surface.nodes is a separate array of objects with longitude, latitude, durationMinutes, and walkDistanceM; it is not the coordinate table inside edges. With includeNodes: false it is empty. includeNodes: true retains up to 30,000 reached nodes and reports diagnostics.surface.nodeEvidenceTruncated. This diagnostic limit does not truncate the raster or street intervals.

Compare operates on the requested surface.values grids from two saved Reach responses. It does not compare fullValues, GeoJSON areas, stop arrays, or individual street edges.

Signs and reachability

For a cell present in both grids, deltaMinutes = after - before. Negative means faster; positive means slower. The interpretation of null depends on both input cells:

An illustrative two-by-two grid makes the distinction concrete. These values are arithmetic examples, not measured network travel times:

before = [10, null, 20, null]
after  = [ 8,   15, null, null]

The comparator returns these exact selected fields for those arrays:

{
  "kind": "compare",
  "schemaVersion": "vigo.standalone.comparison.v1",
  "sign": "after-minus-before",
  "commonCells": 1,
  "newlyReachableCells": 1,
  "noLongerReachableCells": 1,
  "meanChangeMinutes": -2,
  "deltaMinutes": [-2, null, null, null]
}

meanChangeMinutes averages common cells only; it is null if there are no common cells. It excludes both new and lost reachability. Never replace delta nulls with zero before averaging. The count unreachable in both is width * height - commonCells - newlyReachableCells - noLongerReachableCells.

Grid and provenance

The response carries width, height, and bounds; deltaMinutes uses the same northwest-first flat order as Reach. Input City revisions and requested grids must match. Fix bounds explicitly when running a baseline and scenario so cell positions stay comparable.

Keep both original requests and responses. The comparator verifies revision/grid/value compatibility but does not verify matching origins, dates, clocks, modes, cutoffs, or walking policies. Its outer cityRevision comes from the City loaded by the process; the input revision check only compares the two saved inputs. Verify those inputs also belong to the loaded City if you rely on the outer revision as provenance.

Diagnostics explain the computation that ran. They are useful for troubleshooting and profiling, but the high-level result fields remain the values to show to clients.

Where diagnostics live

Transit Route search diagnostics report startSeconds, endSeconds, transfer policy, and horizonScope: "timetable_scan". Endpoint access diagnostics explain selected-stop or coordinate candidate construction. diagnostics.realtime describes an applied supplied snapshot when present; a dataMode label is not an independent prediction-accuracy guarantee.

When a direct walk wins inside a transit request, the top-level route or matrix cell reflects walking while the native diagnostics still describe the transit search. Do not overwrite the returned high-level value with a diagnostic clock or duration.

Timing and counters

queryNs / 1_000_000 converts a native query time to milliseconds. It measures a kernel scope inside dispatch; it is not network latency. Native searches, preparation, geometry materialization, and JSON construction can have different boundaries. Do not sum nested timings or subtract them to infer an isolated cost without checking their scope.

Timetable counters such as scannedDepartures, expandedTripRuns, and relaxedStops count algorithm work, not necessarily distinct trips or stops. Matrix forwardSearches and reverseSearches show execution orientation without changing row/column order. Reach reachedPixels counts finite cells on the requested grid; reachedEdgeCount and reachedEdgeLengthM count directed street edges, so two directions can represent the same physical road. They are not a geographic area measurement or a count of unique road centerlines.

Native result envelope and indices

Native responses contain operation and a typed object under result, plus outer dispatch metadata. The native field reference lists every operation's input and output type. Native result fields are present even when their optional values are null; high-level variant fields can instead be absent.

Timetable operations use indices from timetable.identifiers for the same active service date and policy. stopIds[index] resolves a stop index; tripIds[index] and routeIds[index] resolve a trip and its route. routeIds is parallel to trips, not a deduplicated route catalog. accessMemberStopIds belongs to prepared endpoint-access members, a separate domain. Do not reuse saved numeric indices across changed preparations or timetable activations.

Native timetable.matrix returns a flat origin-major times array of service-day clock seconds. For one A → B pair, the fixture route's departure gives [30600], an 08:30 arrival. Arrive-by gives latest departure clocks instead. journeys is null when not requested; an unreachable numeric slot serializes as null. Street and drive native matrices use flat distances in meters and, for drive, durations in seconds. Read the operation-specific type before interpreting an array named times, values, or distancesM.

Keep a City loaded while sending a sequence of JSON queries through standard input. Streaming returns one result for each request, in order.

One-shot commands open a City for each invocation. stream keeps a City resident and reads one object per line. Every line requires kind; an optional id is echoed even for query errors. Output is one compact JSON object per line, in input order, carrying the request id and a sequence number like the compiler's stream. Blank lines are ignored, and there is no startup handshake.

Transit can reuse a prepared service snapshot only when its source database, access policy, active services, transfer projection, dictionaries, and array layout validate. Missing or invalid optional timetable snapshots fall back to source preparation without writing City files. Realtime and disabled street transfers use source preparation. For repeated calls, keep stream or serve resident; measure fresh-process startup separately from warm query time. The runtime retains immutable shape/alignment data in a bounded cache (1,024 shapes and 64 MiB by default; configurable through VIGO_SHAPE_GEOMETRY_CACHE_MAX_ENTRIES and VIGO_SHAPE_GEOMETRY_CACHE_MAX_BYTES) and shares same-request endpoint evidence even when answer caches are disabled. The shape limit is an upper bound, not reserved memory; it trades a larger possible resident footprint for less repeated geometry preparation.

Full Matrix journeys also share immutable ride and walking evidence within the request, bounded to 4,096 entries and 16 MiB of estimated storage. The key retains the selected endpoint candidates, stop/sequence identities and walking cost; each occurrence keeps its own service clocks. Geometry is unchanged. This storage is discarded after the matrix, including when the query fails. Disabling request caches does not disable this sharing inside one batch.

{"kind":"route","id":"trip-1","origin":{"stopId":"A"},"destination":{"stopId":"B"},"serviceDate":"2026-07-15","time":"07:55","maxWalkKm":0.2}
{"kind":"reach","id":"area-1","origin":{"stopId":"A"},"serviceDate":"2026-07-15","time":"07:55","cutoffsMinutes":[30],"rasterSize":48,"extentRadiusKm":2}

./vigo stream --city ./city < requests.ndjson > results.ndjson

Route, Matrix, Reach/isochrone, Compare, Native, Info, and Capabilities use the same dispatcher. The process retains the latest active timetable; a different service date is allowed and replaces that timetable. This differs from the older Node stream's fixed-date process. Malformed JSON/invalid queries produce per-line errors and the next line can run. A line exceeding 8 MiB terminates the stream. Stream has no query deadline or supervised restart; use HTTP or your own process supervisor for those guarantees. Close stdin to end it.

Start the HTTP service with vigo serve and send query JSON to the endpoints below. The command line and HTTP API use the same request fields.

Endpoints

The path selects the command; a body kind is overwritten accordingly. Send JSON with Content-Type: application/json. Content-Length and bounded chunked HTTP/1.1 bodies are supported. Duplicate/conflicting length headers are rejected. Connections close after a response; there is no keep-alive, WebSocket, HTTP/2, gzip, streaming response, or browser CORS policy in the service. Other methods/paths return 404 after authentication. A same-origin application or reverse proxy can provide a browser integration policy. Every response carries a restrictive Content-Security-Policy; it allows the embedded guide's API console to call this service's own endpoints (connect-src 'self') and nothing else.

Server limits

The executable runs an HTTP front end and a supervised child worker. The worker keeps one City loaded and processes one query at a time; individual queries can use native parallel kernels. Slow request bodies are read outside that worker. Queue deadlines include waiting and writing to the child. A timed-out or failed worker is stopped and replaced. The service holds no per-client session.

Queued HTTP requests retain encoded JSON; only the worker expands nested query fields. Across connections, uploads and queued requests share a 64 MiB encoded-byte admission budget (including normalization headroom). Chunked uploads reserve their configured maximum before reading. Pending response buffers share a 128 MiB budget until socket writes finish. Capacity exhaustion returns 503, including before 100 Continue for rejected uploads. These bounds cover transport buffers, not total process RSS or the City working set; response reading can additionally hold one worker result of up to 64 MiB. Closing, canceling, or expiring a request releases its reservation when its retained work is discarded.

Waiting routes and matrices of at most 1,024 cells receive up to 32 turns or 250 ms of worker time before the oldest waiting analytical request. FIFO order is preserved within each group, and one admission limit covers both groups. This prevents a submitted batch of Reach jobs from monopolizing the waiting queue. The worker completes its current query before switching; a long running query still contributes to latency.

Headers are limited to 16 KiB and 64 header entries. Worker output is limited to 64 MiB per result. Response writing has a 10-second deadline; startup allows up to 60 seconds for a City worker. Oversized responses or worker exits can appear as 504, so split high-detail matrices/rasters rather than retrying the same oversized query indefinitely.

Cancel a request

A named HTTP request (id containing up to 128 letters, digits, hyphens, underscores or periods) can be canceled through DELETE /v1/requests/{id}. The cancellation returns 202; the original request returns 499. Running work is terminated and its worker replaced; queued work is skipped. Retrying an ID while it is active returns 409.

Status codes

The service logs its listening address to stderr. Health routes avoid the computation queue but still share the connection limit. A failed accept or connection setup, such as descriptor exhaustion, drops that connection and the service keeps listening; accept failures pause briefly before the next attempt. If a replacement City worker fails to start, the first failure of each streak is logged with its reason, /readyz returns 503 and queries return 503 while restarts back off exponentially from 250 ms to at most 10 seconds. Use bounded retries with backoff for 503; for 504 first reduce the workload or inspect worker logs. Do not treat a transport error as an unreachable trip.

Send query JSON from your application through HTTP or the command line. An HTTP client needs no VIGO language package.

Use the standalone response fields described in Results and errors. The public Node and Rust result schemas are shared; old internal envelopes are retained only in trace. For reproducible jobs, keep the build identity, capabilities, City revision, complete request, observation timestamps, and output.

A Python standard-library HTTP client needs no VIGO Python package:

import json
import os
import urllib.error
import urllib.request

query = {
    "origin": {"stopId": "A"},
    "destination": {"stopId": "B"},
    "serviceDate": "2026-07-15",
    "time": "07:55",
    "maxWalkKm": 0.2,
}
headers = {"Content-Type": "application/json"}
if os.environ.get("VIGO_API_TOKEN"):
    headers["Authorization"] = "Bearer " + os.environ["VIGO_API_TOKEN"]
request = urllib.request.Request(
    "http://127.0.0.1:8080/v1/route",
    data=json.dumps(query).encode(), headers=headers,
)
try:
    with urllib.request.urlopen(request, timeout=45) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(error.read().decode()) from error
if result.get("status") == "not_found":
    print("No journey:", result.get("reason"))
else:
    print(result["journey"]["arrivalTime"], result["journey"]["legs"])

A JavaScript client can use fetch with an AbortSignal timeout. Read the HTTP status before interpreting JSON; its successful body can still be a blocked result. Keep bearer tokens in server-side integrations or an appropriate authenticated same-origin service. Do not embed a shared deployment token into publicly served application code.

Call the routing kernels directly when you need packed arrays or controls exposed by a native operation.

Use vigo native --city ./city --request kernel-query.json or POST /v1/native. Supply operation, input, and a service date for timetable operations. Native indices must belong to the loaded City and active service date. The HTTP API never accepts a filesystem path inside a query.

{
  "operation": "timetable.identifiers",
  "serviceDate": "2026-07-15"
}

timetable.identifiers returns stopIds, tripIds, routeIds (one per active trip), and accessMemberStopIds. An index is its position in the corresponding array. Resolve each active timetable's IDs before building numeric requests. Cumulative offset arrays start at zero, end at the associated packed-array length, and have one more entry than their group count. Parallel arrays must have equal compatible lengths; indices and times are validated by the kernels.

An ordinary street path uses coordinates and needs no numeric timetable IDs:

{
  "operation": "street.path",
  "input": {
    "originLon": -77.05,
    "originLat": 38.9,
    "destinationLon": -77.03,
    "destinationLat": 38.91,
    "maximumDistanceM": 5000,
    "maximumPoints": 512
  }
}

Native timetable departure, horizon, earliest, and deadline are absolute service-day seconds. High-level horizonMinutes is a duration; native horizon is an end clock. maximumBoardings counts vehicle boardings, so it equals a high-level transfer cap plus one. Access walk times and transfer arrays are seconds, distances are meters. Drive traffic weights use hundredths of seconds. Native output suffixes such as queryNs retain nanoseconds and must not be relabeled milliseconds.

Native Matrix returns a flat array of clock times in seconds: arrival clocks for depart-at, departure clocks for arrive-by. High-level Matrix returns a two-dimensional array of travel durations in minutes. Both use origin row order and destination column order. Unreachable native times are serialized as null.

timetable.pareto exposes native arrival/boarding/walking trade-offs; it is distinct from sampled departure windows. Native overlays operate on packed caller-supplied arrays. realtime.compile compiles explicit effective call times; it does not fetch/decode a provider feed. The native field reference lists every public operation and nested input/result type from the Rust definitions. Optional request fields may be omitted or set to null. Native result objects include every declared field; unavailable optional values are null. The runtime also enforces semantic limits and compatible array domains.

The complete generated dictionary is in Native Rust field reference. It is also part of the offline guide and the engine archive.

Generated for VIGO 0.5.2 from public Rust structs. Regenerate with npm run docs:standalone.

Use the native operation reference for units, index domains, and examples. In requests, an optional field accepts omission or null. Result objects include every listed field; an unavailable optional value is null. Native arrays become JSON arrays, and non-finite result numbers become null. The runtime also checks compatible array lengths, indices, and values.

Source: native/vigo-routing-kernel/src/exact_routing.rs.

Source: native/vigo-routing-kernel/src/exact_routing.rs.

Source: native/vigo-routing-kernel/src/exact_routing.rs.

Source: native/vigo-routing-kernel/src/exact_routing.rs.

Source: native/vigo-routing-kernel/src/exact_routing.rs.

Source: native/vigo-routing-kernel/src/lib.rs.

Source: native/vigo-routing-kernel/src/lib.rs.

Source: native/vigo-routing-kernel/src/lib.rs.